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

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

私はテクニカルライターで、元々エンジニアだったということもあって、社内向け・社外向けを問わず、開発ドキュメントを書いてきました。

この経験をもとに、開発ドキュメントを書くときの手順を整理してみました。また、それぞれのプロセスについて、関連記事も紹介します。

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

著者
Hiroki Zenigami

テクニカルライター。開発者向けのドキュメントを書いています。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。趣味はスプラトゥーンです。

目次

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

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

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

この手順は、開発ドキュメントをどこで公開するのか、あるいは組織のやり方によっても変わると思いますが、基本的にはこのような形だと思います。

なぜこの手順で書くかというと、読者にとってわかりやすく、読みやすい開発ドキュメントを、手戻りを少なく作成できるからです。

例えば、初めから文章を書き始めてしまうと、本来書くべきだったこととは違うことを書いてしまって、修正にたくさんの時間がかかってしまったりします。

そうではなく、書くべきことをしっかりと整理した上で書く、つまり上記の手順に従うことで、効率的に開発ドキュメントを書くことができます。

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

1. 変更要求

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

例えば、

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

こういった変更要求が、まず発生することになると思います。

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

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

2. 要件整理

変更要求が生まれたら、今度はこの変更要求をもとに要件を整理していきます。

具体的には、

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

といった項目について整理していきます。

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

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

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

3. 企画

要件を整理したら、次に文章を書く準備をします。つまり企画します。

企画では、読者とその悩み、そして解決策を決めます。なぜなら、開発ドキュメントは「読者の悩みを解決するため」にあるからです。

例えば電子レンジの取扱説明書について考えてみると、電子レンジの利用者が「使い方が分からない」という悩みを解決するために読むと思います。

つまり、取扱説明書は利用者が分かる言葉づかいで書く必要があります。決して、難しい専門用語を使ったりしてはいけません。

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

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

4. アウトライン作成

企画が完了したら、アウトラインで文章の構成を決めます。このアウトラインは、箇条書きで書いていきます。

なぜ文章を書く前にアウトラインを書くかというと、構成を決める段階で修正をしやすいようにするためです。

例えば、最初から文章を書き始めるとします。もし文章の構成が分かりづらければ、文章ごと修正する必要が出てきます。

ただ、文章というものは単に入れ替えればいいという訳ではありません。これは、文章には「文脈」というものがあるためです。

文脈を踏まえた上で、分かりやすく文章を修正するのは、とても大変な作業になります。

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

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

5. 執筆

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

また、文章を書くときは自動校正ツールを導入しておくと、文章の誤りを防ぐことができます。

加えて、文章を書き終えたら、しっかりと推敲をします。これで、分かりやすく読みやすい文章を作ることができます。

文章の書き方について詳しくは、次の3つの記事をご覧ください。

6. レビュー

文章を書いたら、他の人にレビューしてもらいます。自分ひとりしかいない場合は難しいですが、他にメンバーがいるときは、レビューをしてもらいます。

なぜなら、情報や文章の誤りが見つかって、より分かりやすく読みやすい文章になるからです。

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

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

7. 公開

文章を書いてレビューを通過したら、いよいよ開発ドキュメントを公開します。

公開するにあたって気をつけることはそんなにないですが、いくつかやった方がよいことがあります。

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

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

まとめ

開発ドキュメントを変更する内容が決まってから、公開するまでの基本的な流れを紹介しました。

この記事で全体の流れを把握しつつ、各プロセスについて作業するときは関連記事を読むことで、開発ドキュメントを効率的に書けるようになればと思います。

著者
Hiroki Zenigami

テクニカルライター。開発者向けのドキュメントを書いています。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。趣味はスプラトゥーンです。

関連記事関連書籍
applis
アプリケーション開発について学ぶブログ
お問い合わせ
ご意見・ご質問やお仕事のご依頼などは下記よりお願いいたします
お問い合わせ
© 2020-2022 applis