アカウント名:
パスワード:
微細に書かせるから書きたくなくなるんだよ。
# ドキュメント?欲しけりゃくれてやる# 俺の全てをソースに置いてきた
ソースちゅうのはミクロな視点なので、マクロな視点の読み物は別途あると便利ですよね。各モジュールの目指す役割など、つーかどのソースをまずあたればいいのかがわかるものが、ざっとでも書いてあるとうれしい。あと当初の考えが甘くて苦労したポイントなどが書いてあるとそれだけでもそこが要注意だとわかる。
ソースは結論しか書いてないからその経緯がほしいんですよね何のためにわざわざこんな実装なのか、とかこれは何を意味する処理なのか、とか。ソースコメントは本人視点になりやすくドキュメントは第三者視点になりやすい。
倒産した会社のソースを引き継いだときに渇望したのは要件定義と倒産までの運用内容の経緯でした。ソースなんて読みゃわかるし。
そうなんですよね。マクロな視点が欲しいんです。なのになぜかExcelにコードを日本語に直したレベルの詳細なものを書いてからじゃないとコーディングさせてくれないプロジェクトが存在するんですよ。いらない詳細なドキュメントばっかで、どのモジュールが何をするものなのかつながりなんかの資料が存在しないひどいプロジェクトでした。
どうしてそんなことになっているかというと、そのドキュメントがあることで何らかの免責になる人がいるんでしょうね。
ドキュメントを作ったぞ、と。これに書いてあるじゃないかと。でも、そんなドキュメントが免責になるということは要求してる側はそのドキュメントを見ていない/理解していないということ。あるだけでいいという種類のものなんでしょうね。つまり無駄なもの。
免責にならないという事例を沢山つくらないと結局、改善しないのかもしれません。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
人生の大半の問題はスルー力で解決する -- スルー力研究専門家
簡潔に説明する文章だけならいいんだよ (スコア:1)
微細に書かせるから書きたくなくなるんだよ。
# ドキュメント?欲しけりゃくれてやる
# 俺の全てをソースに置いてきた
Re:簡潔に説明する文章だけならいいんだよ (スコア:0)
ソースちゅうのはミクロな視点なので、マクロな視点の
読み物は別途あると便利ですよね。
各モジュールの目指す役割など、つーかどのソースをまず
あたればいいのかがわかるものが、ざっとでも書いてあると
うれしい。
あと当初の考えが甘くて苦労したポイントなどが書いてあると
それだけでもそこが要注意だとわかる。
Re:簡潔に説明する文章だけならいいんだよ (スコア:1)
ソースは結論しか書いてないからその経緯がほしいんですよね
何のためにわざわざこんな実装なのか、とか
これは何を意味する処理なのか、とか。
ソースコメントは本人視点になりやすくドキュメントは第三者視点になりやすい。
倒産した会社のソースを引き継いだときに渇望したのは
要件定義と倒産までの運用内容の経緯でした。
ソースなんて読みゃわかるし。
Re: (スコア:0)
そうなんですよね。
マクロな視点が欲しいんです。
なのになぜかExcelにコードを日本語に直したレベルの詳細なものを書いてからじゃないと
コーディングさせてくれないプロジェクトが存在するんですよ。
いらない詳細なドキュメントばっかで、どのモジュールが何をするものなのかつながりなんかの資料が存在しない
ひどいプロジェクトでした。
Re: (スコア:0)
どうしてそんなことになっているかというと、
そのドキュメントがあることで何らかの免責になる人がいるんでしょうね。
ドキュメントを作ったぞ、と。
これに書いてあるじゃないかと。
でも、そんなドキュメントが免責になるということは
要求してる側はそのドキュメントを見ていない/理解していないということ。
あるだけでいいという種類のものなんでしょうね。
つまり無駄なもの。
免責にならないという事例を沢山つくらないと
結局、改善しないのかもしれません。