devとdocumentに関するakkun_choiのブックマーク (3)
-
最近は時間を作ってEffective Javaの2版をよんでます。 Effective Java (Java Series) 作者: Joshua Bloch出版社/メーカー: Prentice Hall発売日: 2008/05/08メディア: ペーパーバック購入: 6人 クリック: 65回この商品を含むブログ (42件) を見る ほとんど1版と同じ内容ですが、"Item 44: Write doc comments for all exposed APIelements" を読んでよくまとまってるなと思ったので、触発されてメモがてらに私のやり方を。 引用の2段落目は基本的に超約。 どこに書くか If an API is to be usable, itmust be documented. ユーザが利用可能なすべてのAPIにJavadocを書く。 これはとりあえず必須だと思います。ち
-
僕の考えは、以下のような感じ。 (1) ドキュメント︵設計書だろうが仕様書だろうが︶は、﹁誰に何をどう伝えるべきか﹂を考えれば、何を揃えればいいかは自然と決まってくる。そして、誰が読んでも意味がないと判断されるドキュメントは意味がないので書かない。 (2) ﹁基本設計書﹂や﹁詳細設計書﹂や﹁外部設計書﹂や﹁内部設計書﹂という言葉があるが、肝心なのは﹁誰に何を伝えるか﹂であり、伝えたいことや認識あわせの単位でドキュメントが作られればそれでいい。それらをまとめて﹁○○設計書﹂とするかどうかは、顧客がそうしたければ好きにすれば良い︵そこまでやる義務は開発側にはないと思う︶。 (3) アーキテクトの仕事は、各作業者が何をしたらいいか迷うことなく作業ができるように﹁決めごとをしていくこと﹂。その決めごとは、すべてドキュメント化されるべきであり、そのためには﹁誰に何をどう伝えるべきか﹂を考えていけば、
-
﹁How non-programmers use documentation﹂という記事がありました。 面白かったので一部を訳してみました。 間違いなどがある可能性があるので、詳細は原文をご参照下さい。 この記事は、プログラマではない人がどのようにドキュメントを参照するかをまとめています。 これを参考にして、ユーザフレンドリーなドキュメンテーションを作ってくださいと書いてありました。 Internal and on-line
-
1
Javadocを書く - しげるメモ
ドキュメントとして何を書くか？
プログラマではない人によるドキュメント(ヘルプ)の使い方:Geekなぺーじ
