アカウント名:
パスワード:
ドキュメントの質の基準を明確にする基準に基づいて評価する評価にインセンティブを与える
読み手のレベルが確定しないと書けないってのはありますね。こっちにとって当たり前のキーワードが不明だと質問されてもそれぐらい常識だろ、としか返せない。
あとこっちもシステム全体の仕様のサブセットをコーディングしているだけなのに、そもそものシステムの思想なぞ求められても困ります。
私は、未来の自分宛の読み物として書くことが多いですね。全体の把握のための概論と、あとはおおむね苦労話を「読み物」として。細かい動作はコードを見ろという方針、現在の自分がひっかっかった所は未来の自分もまたひっかかるだろうと予想して。
後はもうFAQにしちゃう。誰か読んでくれて、質問来たらまずはそれに答え、それをそのままFAQに追加。
話は変わりますが、ソースコードを開いた先頭に、「このソースは何をする(つもりの)ものである」と一行でいいから書いてくれんかなぁ。追いかける時の安心度が違うのよ。ファイル名から類推できないからソースを開いて、ライセンスばーっとあって、部品レベルの関数が続くと読み始めの場所を探すだけで疲れる。
話は変わりますが、ソースコードを開いた先頭に、「このソースは何をする(つもりの)ものである」と一行でいいから書いてくれんかなぁ。追いかける時の安心度が違うのよ。
ライセンス込みでコピペして修正し忘れそうだけど。
コードしかメンテせずに、知っててコメントを古いまま放置するやつもいる。
「何をする」つもりで作り始めたけど、作っているうちにもっといい方法を思いついたので方針を転換した → 初期のコメントは放置なんてのもある。
全部おれのコードだ。
派生クラスのドキュメントを書いたら、基底クラスの仕様について、微に入り細に入り、重箱の隅をつつくように、レビューで突っ込まれることが多々あります。突っ込んでくれるだけマシですが、その基底クラスを設計して、使用することを指示した本人が突っ込んでいるのは、なぜ? 挙句の果てに、基底クラスの不具合が見つかったりすることも多い。
>評価にインセンティブを与える
アウトソースするとここがまず削られるので、内製を促進しないといけないね。
ユーザーの立場に近い人間が製品をテストしながらドキュメントとりまとめで動いてくれればいいですね。最初は結構ラフに技術者よりで書いてから、ここわかんないとかもうちょっと詳しくとか、実物とかみ合ってない箇所があるとか実際操作しながら校正してくれると本当に役に立つドキュメントに近づきます。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
日々是ハック也 -- あるハードコアバイナリアン
だれが読むのかを明確にする (スコア:1)
ドキュメントの質の基準を明確にする
基準に基づいて評価する
評価にインセンティブを与える
Re:だれが読むのかを明確にする (スコア:1)
読み手のレベルが確定しないと書けないってのはありますね。
こっちにとって当たり前のキーワードが不明だと質問されても
それぐらい常識だろ、としか返せない。
あとこっちもシステム全体の仕様のサブセットをコーディングしているだけなのに、
そもそものシステムの思想なぞ求められても困ります。
私は、未来の自分宛の読み物として書くことが多いですね。
全体の把握のための概論と、あとはおおむね苦労話を「読み物」として。
細かい動作はコードを見ろという方針、現在の自分がひっかっかった所は
未来の自分もまたひっかかるだろうと予想して。
後はもうFAQにしちゃう。誰か読んでくれて、質問来たらまずはそれに答え、
それをそのままFAQに追加。
話は変わりますが、ソースコードを開いた先頭に、「このソースは何をする
(つもりの)ものである」と一行でいいから書いてくれんかなぁ。追いかける時の
安心度が違うのよ。
ファイル名から類推できないからソースを開いて、ライセンスばーっとあって、
部品レベルの関数が続くと読み始めの場所を探すだけで疲れる。
Re:だれが読むのかを明確にする (スコア:1)
話は変わりますが、ソースコードを開いた先頭に、「このソースは何をする
(つもりの)ものである」と一行でいいから書いてくれんかなぁ。追いかける時の
安心度が違うのよ。
ライセンス込みでコピペして修正し忘れそうだけど。
コードしかメンテせずに、知っててコメントを古いまま放置するやつもいる。
「何をする」つもりで作り始めたけど、作っているうちにもっといい方法を思いついたので方針を転換した
→ 初期のコメントは放置
なんてのもある。
全部おれのコードだ。
Re: (スコア:0)
派生クラスのドキュメントを書いたら、基底クラスの仕様について、微に入り細に入り、重箱の隅をつつくように、レビューで突っ込まれることが多々あります。突っ込んでくれるだけマシですが、その基底クラスを設計して、使用することを指示した本人が突っ込んでいるのは、なぜ? 挙句の果てに、基底クラスの不具合が見つかったりすることも多い。
Re: (スコア:0)
>評価にインセンティブを与える
アウトソースするとここがまず削られるので、内製を促進しないといけないね。
Re: (スコア:0)
ユーザーの立場に近い人間が製品をテストしながらドキュメントとりまとめで動いてくれればいいですね。
最初は結構ラフに技術者よりで書いてから、ここわかんないとかもうちょっと詳しくとか、実物とかみ合ってない箇所があるとか実際操作しながら校正してくれると本当に役に立つドキュメントに近づきます。