開発ドキュメントを書くことになったとき、何から始めればよいか、どう公開まで進めればいいか、よく分からないかもしれません。
私はテクニカルライターで、元々エンジニアだったということもあって、社内向け・社外向けを問わず、開発ドキュメントを書いてきました。この経験をもとに、開発ドキュメントを書くときの手順を整理してみました。また、それぞれのプロセスについて、関連記事も紹介します。
この記事を読むことで、開発ドキュメントを書くときの全体の流れが分かり、不安なく効率的に公開まで進められたらと思います。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
開発ドキュメントを公開するまでの基本的な手順
開発ドキュメントを効率的に書くための基本的な手順は、次のような形になります。
| 手順 | 項目 | 概要 |
|---|---|---|
| 1 | 変更要求 | 開発ドキュメントに対する変更要求が作成される |
| 2 | 要件整理 | 変更要求を元に要件を整理する |
| 3 | 企画 | 読者とその悩み、解決策を決める |
| 4 | アウトライン作成 | 文章の構成を決める |
| 5 | 執筆 | 文章を作成・推敲する |
| 6 | レビュー | 関係者に確認してもらう |
| 7 | 公開 | 開発ドキュメントを公開する |
この手順は、開発ドキュメントをどこで公開するのか、あるいは組織のやり方によっても変わると思いますが、基本的にはこのような形だと思います。なぜこの手順で書くかというと、読者にとってわかりやすく、読みやすい開発ドキュメントを、手戻りを少なく作成できるからです。
例えば、初めから文章を書き始めてしまうと、本来書くべきだったこととは違うことを書いてしまって、修正にたくさんの時間がかかってしまったりします。そうではなく、書くべきことをしっかりと整理した上で書く、つまり上記の手順に従うことで、効率的に開発ドキュメントを書くことができます。
それでは、それぞれのプロセスについて簡単に説明していきます。
1. 変更要求
開発ドキュメントを書くことになったとき、そこには何かしらの変更要求がある、ということになります。例えば、次のような変更要求がまず発生することになると思います。
- メンバーのために開発環境構築の手順をまとめたい
- APIに機能を追加したので、開発ドキュメントに追加してほしい
- 既存の開発ドキュメントを修正したい
この変更要求のときに集める情報をあらかじめ決めておくと、あとで要件を整理するときに、とてもスムーズに行うことができます。
この変更要求のときに集めるべき情報については、「開発ドキュメントの変更要求のときに集めるべき情報」をご覧ください。
2. 要件整理
変更要求が生まれたら、今度はこの変更要求をもとに要件を整理していきます。具体的には、次のような項目について整理していきます。
- どのページに、何を、いつまでに書くか
- レビュアーは誰か
- 参考となる資料にはどんなものがあるか
仮に「どこに何を書くか」が曖昧な状態で書き始めたとします。この場合、書いたあとで「書く場所が違う」と言われたり、「情報が間違っている」と言われたりすることがあります。
あるいはレビュアーを決めておかないと、開発ドキュメントの公開直前になって、別の人から修正を求められたりすることもあります。こういった問題を防ぐのが、要件整理の目的です。
要件整理について詳しくは、「開発ドキュメントの要件を整理する方法」をご覧ください。
3. 企画
要件を整理したら、次に文章を書く準備をします。つまり企画します。企画では、読者とその悩み、そして解決策を決めます。なぜなら、開発ドキュメントは「読者の悩みを解決するため」にあるからです。
例えば電子レンジの取扱説明書について考えてみると、電子レンジの利用者が「使い方が分からない」という悩みを解決するために読むと思います。つまり、取扱説明書は利用者が分かる言葉づかいで書く必要があります。決して、難しい専門用語を使ったりしてはいけません。
この読者と悩み、解決策が曖昧だと、読者にとって分かりづらい文章になってしまいます。
文章を書く前に、まず企画をするところから始めます。開発ドキュメントの企画について詳しくは、「開発ドキュメントを書く前に決めること」をご覧ください。
4. アウトライン作成
企画が完了したら、アウトラインで文章の構成を決めます。このアウトラインは、箇条書きで書いていきます。なぜ文章を書く前にアウトラインを書くかというと、構成を決める段階で修正をしやすいようにするためです。
例えば、最初から文章を書き始めるとします。もし文章の構成が分かりづらければ、文章ごと修正する必要が出てきます。ただ、文章というものは単に入れ替えればいいという訳ではありません。これは、文章には「文脈」というものがあるためです。
文脈を踏まえた上で、分かりやすく文章を修正するのは、とても大変な作業になります。このため、アウトラインの段階で話の流れが分かりやすいかどうかを、しっかりと考えます。もし分かりづらくても、箇条書きの段階なので、修正がとても簡単です。
アウトラインの作成について詳しくは、「開発ドキュメントにおけるアウトラインの書き方」をご覧ください。
5. 執筆
アウトラインができたら、実際の文章を書いていきます。このときは、「基本的な書き方」や「表現方法」といったものをふまえた上で書いていきます。
また、文章を書くときは自動校正ツールを導入しておくと、文章の誤りを防ぐことができます。加えて、文章を書き終えたら、しっかりと推敲をします。これで、分かりやすく読みやすい文章を作ることができます。文章の書き方について詳しくは、次の3つの記事をご覧ください。
また、テクニカルライティングに関する本を読むことで、よりよい文書が書けるようになります。これについては次の記事で詳しく解説していますので、あわせてご覧ください。
6. レビュー
文章を書いたら、他の人にレビューしてもらいます。自分ひとりしかいない場合は難しいですが、他にメンバーがいるときは、レビューをしてもらいます。なぜなら、情報や文章の誤りが見つかって、より分かりやすく読みやすい文章になるからです。
例えば情報に誤りがあると、読み手の時間を余計に奪ってしまうことになります。企業として開発ドキュメントを公開している場合は、信頼性の問題にもなり得ます。
このため、開発ドキュメントを公開する前に、しっかりとレビューをしてもらいます。レビューについて詳しくは、「開発ドキュメントをレビューする方法」をご覧ください。
7. 公開
文章を書いてレビューを通過したら、いよいよ開発ドキュメントを公開します。公開するにあたって気をつけることはそんなにないですが、いくつかやった方がよいことがあります。
公開するときに気をつけることを押さえておくことで、より多くの人に読んでもらったり、公開に対するリスクを減らすことができます。
開発ドキュメントの公開について詳しくは、「開発ドキュメントを公開したときにやること」をご覧ください。
まとめ
開発ドキュメントを変更する内容が決まってから、公開するまでの基本的な流れを紹介しました。この記事で全体の流れを把握しつつ、各プロセスについて作業するときは関連記事を読むことで、開発ドキュメントを効率的に書けるようになればと思います。
