設計書のテンプレートを考えてみる

前回に引き続き、リファレンスを書いているのですが、仕事でオリジナルの設計書を書いたことがないので、どうやって書いていいのか悩んでいます。

そこで、何か参考にしながら書けばいいのではないか、と思い、いつもお世話になっているgoogle codeのAPI仕様書を参考にしながら、テンプレートを作ってみたいと思います。

まずはじめに、APIの全体像を紹介するためのHomeがあって、次にDocumentに入ります。Documentでは、いくつかの構成にわけてさらに詳しい説明を展開しています。

で、いくつかのサンプルソースが紹介されていて、その後は、関数やメソッドのリファレンスが展開されていました。

以上から、下のような構成になっている感じです。

・Home   APIの概要を説明する(大まかに説明する) ・Document   いくつかのテーマに分かれて開設がされている ・Example   サンプルソースの紹介 ・Reference   関数、メソッド、オブジェクトについての詳細

完全に同じではないと思いますが、だいたいこんな感じなのではと。

で、coldfusion-addonに関しては、関数系の説明を多くしたいので、リファレンスの部分に下のテーブルを追加するような形を考えました。

argument	type	required	default	explain

と引数をより詳しく書いたテーブルにすることでわかりやすくなるのではないかと思いました。

少しでもオリジナリ感を出したいと思ったので、google codeのようなリファレンスの返り値と詳細説明に加え、引数、型、デフォルト値、requiered区の列を追加しました。

これで読んでいる方が少しでも直感的に理解してくれるとうれしいなと思いました。