アカウント名:
パスワード:
ドキュメントの質の基準を明確にする基準に基づいて評価する評価にインセンティブを与える
読み手のレベルが確定しないと書けないってのはありますね。こっちにとって当たり前のキーワードが不明だと質問されてもそれぐらい常識だろ、としか返せない。
あとこっちもシステム全体の仕様のサブセットをコーディングしているだけなのに、そもそものシステムの思想なぞ求められても困ります。
私は、未来の自分宛の読み物として書くことが多いですね。全体の把握のための概論と、あとはおおむね苦労話を「読み物」として。細かい動作はコードを見ろという方針、現在の自分がひっかっかった所は未来の自分もまたひっかか
派生クラスのドキュメントを書いたら、基底クラスの仕様について、微に入り細に入り、重箱の隅をつつくように、レビューで突っ込まれることが多々あります。突っ込んでくれるだけマシですが、その基底クラスを設計して、使用することを指示した本人が突っ込んでいるのは、なぜ? 挙句の果てに、基底クラスの不具合が見つかったりすることも多い。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
私は悩みをリストアップし始めたが、そのあまりの長さにいやけがさし、何も考えないことにした。-- Robert C. Pike
だれが読むのかを明確にする (スコア:1)
ドキュメントの質の基準を明確にする
基準に基づいて評価する
評価にインセンティブを与える
Re: (スコア:1)
読み手のレベルが確定しないと書けないってのはありますね。
こっちにとって当たり前のキーワードが不明だと質問されても
それぐらい常識だろ、としか返せない。
あとこっちもシステム全体の仕様のサブセットをコーディングしているだけなのに、
そもそものシステムの思想なぞ求められても困ります。
私は、未来の自分宛の読み物として書くことが多いですね。
全体の把握のための概論と、あとはおおむね苦労話を「読み物」として。
細かい動作はコードを見ろという方針、現在の自分がひっかっかった所は
未来の自分もまたひっかか
Re:だれが読むのかを明確にする (スコア:0)
派生クラスのドキュメントを書いたら、基底クラスの仕様について、微に入り細に入り、重箱の隅をつつくように、レビューで突っ込まれることが多々あります。突っ込んでくれるだけマシですが、その基底クラスを設計して、使用することを指示した本人が突っ込んでいるのは、なぜ? 挙句の果てに、基底クラスの不具合が見つかったりすることも多い。