目次

開発ドキュメントを公開するまでの基本的な7つの手順

本サイトはアフィリエイトプログラムを利用した広告を表示しています

開発ドキュメントを書くことになったとき、何から始めればよいか、どう公開まで進めればいいか、よく分からないかもしれません。

私はテクニカルライターで、元々エンジニアだったということもあって、社内向け・社外向けを問わず、開発ドキュメントを書いてきました。この経験をもとに、開発ドキュメントを書くときの手順を整理してみました。また、それぞれのプロセスについて、関連記事も紹介します。

この記事を読むことで、開発ドキュメントを書くときの全体の流れが分かり、不安なく効率的に公開まで進められたらと思います。

著者
Hiroki Zenigami

テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。

テクニカルライティングを学ぶ

わかりやすい文章の書き方が学べる入門をnoteで公開しました。ブログやドキュメントなどを書くときにお役立てください。

開発ドキュメントを公開するまでの基本的な手順

開発ドキュメントを効率的に書くための基本的な手順は、次のような形になります。

手順項目概要
1変更要求開発ドキュメントに対する変更要求が作成される
2要件整理変更要求を元に要件を整理する
3企画読者とその悩み、解決策を決める
4アウトライン作成文章の構成を決める
5執筆文章を作成・推敲する
6レビュー関係者に確認してもらう
7公開開発ドキュメントを公開する

この手順は、開発ドキュメントをどこで公開するのか、あるいは組織のやり方によっても変わると思いますが、基本的にはこのような形だと思います。なぜこの手順で書くかというと、読者にとってわかりやすく、読みやすい開発ドキュメントを、手戻りを少なく作成できるからです。

例えば、初めから文章を書き始めてしまうと、本来書くべきだったこととは違うことを書いてしまって、修正にたくさんの時間がかかってしまったりします。そうではなく、書くべきことをしっかりと整理した上で書く、つまり上記の手順に従うことで、効率的に開発ドキュメントを書くことができます。

それでは、それぞれのプロセスについて簡単に説明していきます。

1. 変更要求

開発ドキュメントを書くことになったとき、そこには何かしらの変更要求がある、ということになります。例えば、次のような変更要求がまず発生することになると思います。

  • メンバーのために開発環境構築の手順をまとめたい
  • APIに機能を追加したので、開発ドキュメントに追加してほしい
  • 既存の開発ドキュメントを修正したい

この変更要求のときに集める情報をあらかじめ決めておくと、あとで要件を整理するときに、とてもスムーズに行うことができます。

この変更要求のときに集めるべき情報については、「開発ドキュメントの変更要求のときに集めるべき情報」をご覧ください。

スポンサーリンク

2. 要件整理

変更要求が生まれたら、今度はこの変更要求をもとに要件を整理していきます。具体的には、次のような項目について整理していきます。

  • どのページに、何を、いつまでに書くか
  • レビュアーは誰か
  • 参考となる資料にはどんなものがあるか

仮に「どこに何を書くか」が曖昧な状態で書き始めたとします。この場合、書いたあとで「書く場所が違う」と言われたり、「情報が間違っている」と言われたりすることがあります。

あるいはレビュアーを決めておかないと、開発ドキュメントの公開直前になって、別の人から修正を求められたりすることもあります。こういった問題を防ぐのが、要件整理の目的です。

要件整理について詳しくは、「開発ドキュメントの要件を整理する方法」をご覧ください。

3. 企画

要件を整理したら、次に文章を書く準備をします。つまり企画します。企画では、読者とその悩み、そして解決策を決めます。なぜなら、開発ドキュメントは「読者の悩みを解決するため」にあるからです。

例えば電子レンジの取扱説明書について考えてみると、電子レンジの利用者が「使い方が分からない」という悩みを解決するために読むと思います。つまり、取扱説明書は利用者が分かる言葉づかいで書く必要があります。決して、難しい専門用語を使ったりしてはいけません。

この読者と悩み、解決策が曖昧だと、読者にとって分かりづらい文章になってしまいます。

文章を書く前に、まず企画をするところから始めます。開発ドキュメントの企画について詳しくは、「開発ドキュメントを書く前に決めること」をご覧ください。

4. アウトライン作成

企画が完了したら、アウトラインで文章の構成を決めます。このアウトラインは、箇条書きで書いていきます。なぜ文章を書く前にアウトラインを書くかというと、構成を決める段階で修正をしやすいようにするためです。

例えば、最初から文章を書き始めるとします。もし文章の構成が分かりづらければ、文章ごと修正する必要が出てきます。ただ、文章というものは単に入れ替えればいいという訳ではありません。これは、文章には「文脈」というものがあるためです。

文脈を踏まえた上で、分かりやすく文章を修正するのは、とても大変な作業になります。このため、アウトラインの段階で話の流れが分かりやすいかどうかを、しっかりと考えます。もし分かりづらくても、箇条書きの段階なので、修正がとても簡単です。

アウトラインの作成について詳しくは、「開発ドキュメントにおけるアウトラインの書き方」をご覧ください。

スポンサーリンク

5. 執筆

アウトラインができたら、実際の文章を書いていきます。このときは、「基本的な書き方」や「表現方法」といったものをふまえた上で書いていきます。

また、文章を書くときは自動校正ツールを導入しておくと、文章の誤りを防ぐことができます。加えて、文章を書き終えたら、しっかりと推敲をします。これで、分かりやすく読みやすい文章を作ることができます。文章の書き方について詳しくは、次の3つの記事をご覧ください。

また、テクニカルライティングに関する本を読むことで、よりよい文書が書けるようになります。これについては次の記事で詳しく解説していますので、あわせてご覧ください。

6. レビュー

文章を書いたら、他の人にレビューしてもらいます。自分ひとりしかいない場合は難しいですが、他にメンバーがいるときは、レビューをしてもらいます。なぜなら、情報や文章の誤りが見つかって、より分かりやすく読みやすい文章になるからです。

例えば情報に誤りがあると、読み手の時間を余計に奪ってしまうことになります。企業として開発ドキュメントを公開している場合は、信頼性の問題にもなり得ます。

このため、開発ドキュメントを公開する前に、しっかりとレビューをしてもらいます。レビューについて詳しくは、「開発ドキュメントをレビューする方法」をご覧ください。

7. 公開

文章を書いてレビューを通過したら、いよいよ開発ドキュメントを公開します。公開するにあたって気をつけることはそんなにないですが、いくつかやった方がよいことがあります。

公開するときに気をつけることを押さえておくことで、より多くの人に読んでもらったり、公開に対するリスクを減らすことができます。

開発ドキュメントの公開について詳しくは、「開発ドキュメントを公開したときにやること」をご覧ください。

まとめ

開発ドキュメントを変更する内容が決まってから、公開するまでの基本的な流れを紹介しました。この記事で全体の流れを把握しつつ、各プロセスについて作業するときは関連記事を読むことで、開発ドキュメントを効率的に書けるようになればと思います。

あわせて読みたい

著者
Hiroki Zenigami

テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。

スポンサーリンク

ブログをはじめよう

技術ブログの始め方を、たくさんの画像で分かりやすく解説しました。これまでブログをやったことがない人でも、エンジニアにとって重要なブログを今日から始められます。

ブログをはじめる