ドキュメントの作り方が分かりません。

今会社の研修でPHPを使った自作のシステムを開発しているのですが、トレーナーの方にドキュメントを作るようにと指示を受け、自分で調べてみたのですがどのように作ればいいのかさっぱり分かりません。
自分で作成した物には、変数の使い道、どのページに移動するのか、メソッドの役割を箇条書きにしたのですが、こんな物で良いのでしょうか？何か付けくわえた方がいい内容があれば教えてください。
よろしくお願いします。

行動規範の内容に同意します

回答4件

ベストアンサー

これは永遠のテーマですね。
ドキュメントの作成・メンテナンスについては、100人いれば100通りの持論があり、また皆が皆、常に試行錯誤（＝改善？）しているというのが正直なところではないでしょうか？

しかし、それでは仕事にならないので、どんなプロジェクトであれ、多かれ少なかれ「プロジェクト標準」というものがありますし、プロジェクトの最初の工程として、どんなドキュメントを成果物として作成するかをお客様と認識合わせするプロセスがあります。

それで、外部の人の意見、工夫している点は非常に参考になるのですが、まずは YukiSiinaさんご自身の会社ではどんな「標準」が定められているのか、諸先輩はどのようなドキュメントを書いていらっしゃるのかを「良く見て学ぶ」のが先決です。

内容を眺めてみても、最初は全く分からないかもしれませんが、初めは

ドキュメント体系（どんな種類が作成されているか）
各ドキュメントの章立て（書かれている項目）
どんなフォーマットや文体で書かれているか

のような「見た目」だけでも良いので、良く見て学んでください。

研修ではどの程度のプログラム（システム）を作成されるのか、またどの程度のドキュメントが求められているのかが全く分からないので、具体的なコメントができませんけれども、是非とも

実装（プログラムのソースコード）の説明を書くのではない
プログラム（システム）の仕様を書く

という点を意識して書かれると良いと思います。

簡単なコメントは必要だとしても、細かな実装はソースコードを読めば分かるようになっているべきです。
一方、どのような入力に対してどんな結果を返すか（どんな動作をするか）は、実装を進める際の道標になると同時に、出来上がったものが「仕様通り」かどうかを判定する物差しでもあるので、必須です。

それと、研修中はカリキュラムの関係で時間が無いかもしれませんが…
最初は誰でも初心者なので、たとえうるさがられても、一気に完成させようとせず、要所要所で小まめに見てもらう（＝レビューしてもらう）ようにしてください。
どんなベテランでも品質担保のためにピアレビューが欠かせないのですが、慣れないうちは尚のこと頻繁にレビューしてもらうことで、早く「標準」を身につけられるようになります。

以上が初心者向けの提言でした。

これから先は、少し長くなりますが、ドキュメンテーションに関する持論です。
言うは易く行なうは固しですが…

ちょっと逆説的ですが、良いドキュメンテーションの最大の秘訣は、「極力書かない」ことです。
つまり、本当に「必要不可欠な情報を厳選」し、できるだけコンパクトに書くべきであり、しかも、後で読むために書くのではなく、「必要な時」に「必要な分」ずつ書くのが鉄則です。

というのは、ドキュメンテーションにおいて最も問題となるのは、必要なドキュメントが不足している事ではなく、存在しているドキュメントが「実情と乖離」してしまう事だからです。嘘を書いてあるドキュメントほど厄介なものはありません！
実際に動いているシステムとの整合性を維持するコストは、ドキュメントの量に比例して爆発的に増大します。

しかも、多くの場合、次にドキュメントを詳しく読むのは、システム／ドキュメントに変更を加える必要が生じた時ではないでしょうか？

ですから、大量のドキュメントを「後追い」で作成する事は、生産性を著しく阻害する一方で、品質の向上にはそれ程役立たないのです。

ドキュメントと言ってもいろんな種類がありますし、分類の仕方にも色々な流儀がありますが、設計書を「外部設計書/内部設計書/詳細設計書」と分類する流儀について少しコメントします。
これはウォーターフォール型開発プロセスの場合の一般的な分類です。

＃そもそもドキュメントとして、いつ何をどこまで書くかは、開発プロセスと密接に関わっているので、ドキュメントの事だけを切り離して議論しても意味がないのですが。。

「要件」通りのシステムを作成するために、外部設計→内部設計→詳細設計と段階的に「仕様」を詳細化し、具体的な「実装」（＝コーディング）へとブレークダウンして行くので、「外部設計書/内部設計書/詳細設計書」と形式的に分けて作成すると、類似の情報がいろんな場所に分散されてしまい、整合性の維持が困難になります。

それで、工程別ではなく「内容」によって分類し、外部設計の時点ではその時点で必要な情報だけを記載します。次いで、内部設計工程では、その時点で詳細化された情報を、同じドキュメントに「追記」します。
このように関連する情報を一箇所に集約させる書き方をする、しかも体裁を整えるために後追いで書くのではなく、設計上「必要なタイミング」で「必要な情報だけ」を記載して行くことで、品質を作り込むための道具とすることができます。

システム設計において、モジュール分割はとても重要な作業なので、モジュール間の依存関係を視覚的に確認できるダイアグラムを書くのは非常に有用です。
一口にモジュール間の依存関係といっても、目的に応じて様々な表現法がありますので、「プロジェクト標準」に沿った書き方に早く慣れてください。

一方、詳細設計書はソースコードと密接に関連しているので、別ドキュメントにするのではなくソースコードと一体で管理できるようにすることが望ましいです。

とはいえ、ソースコードはリファクタリング等で大きく変更される可能性があるので、必要以上に詳細にコメントを記載する事は得策ではありません。
変数の説明をコメントに記載する位なら、意味の分かる変数名にリファクタリングする方がずっと意味があります。
むしろ、各部分の処理の意味、処理の前後でデータフォーマットがどのように変化するか、その実装方法が採用された経緯など、システムの仕様を後から思い起こすのに役立つ情報を簡潔に記載します。

もしPHPUnitのようなテストツールを使用可能なら、テストケースの詳細な説明をコメントに記載することで「動く詳細設計書」とすることができます。（ソースコードの場合とは逆に、テストクラスのコメントは仕様を詳細に説明するべきです。）

一般に誤解されている点ですが…、XXUnitのような単体テストツールは、文字通り単体テストのためのツールでテストクラスは必要に迫られて泥縄式に作成されるケースが多いですが、元々はテスト駆動開発プロセスにおける詳細設計のためのツールとして開発されたものです。
詳細設計時には、テストクラスの「判定条件」（＝仕様）と、モジュールの骨組みだけを記載します。
実装工程では、実際に仕様通りに動くことを確かめつつモジュール内部を作り込んで行きます。

こうして実際に必要なタイミング（詳細設計＆実装の工程）で作成したテストクラスは、仕様確認やリファクタリングなど必要な時にはいつでも実際に動かして「使う」ことができます。
このような詳細設計書であれば、品質の作り込みに直接役立つと同時に、ソースコードと整合性の取れていることが常に保証されています。

以上は「理想」であり、現実はなかなか理想通りに行かないものではありますが、しっかりとしたポリシーを持った上で、個々のドキュメントの具体的な書き方を学んで行くと良いです。

この部分については、まずは社内のお手本に目を向けることが重要ですけれども、ネット上にも有用な情報が多数見つけられると思います。

手始めに、下記の「まとめ」を足掛かりとして、色々な解説やサンプルに目を通してみてください。

（参考）仕様書を書くための技術

以上、いくらかでもご参考になれば幸いです。

投稿2015/08/11 16:03