ドキュメントに固執せよ - gfnweb

どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント

[tettekete37564]

コードを読めば何をやっているかは分かっても、何のために何でその実装なのかは分からない。つまり実装からその要件は分からないとという事。特にバグがあった時とかね。

[sgo2]

「コンピュータが期待する動作をするコード」と「人間が期待するよう解釈する文章」では前者の方が遥かに簡単に書ける。後者は個や状況で反応が変わり過ぎる。

[nyankosenpai]

人類の多くには言語化する力がないし、言語を読み取って行動することも苦手としているのだ。けっこうな特殊能力だと思います

[kaakaa_hoe]

whatよりhow、howよりwhy、whyよりwhy not。記録残さないと後々変更する時に観点漏れるよね。

[hitotakuchan]

ドキュメントのないソフトウェアは全て負債である

[carrier_pigeon]

ありがたい文書。why/why not がないと困る。次の dev も困るし ops も困る。ソフトウェアは運用フェーズがライフサイクルで一番長いし、嘘があるというのは更新プロセスを定義してないだけで書かない理由にはならない。

[hdannoue]

ドキュメントは、言語で標準化された事象や現象は書きやすいし、共有性も高く、利益もある。しかし、バリエーションあることや複雑な構造は記述しにくいし、読み手に伝わりにくいので、コストに見合わない。

[choota]

強いエンジニアは文章も書けるし、弱いエンジニアは文章苦手。強いエンジニアはそんなに数いないので、結果文章は置き去りにされる。

[khtno73]

だからSIerは要件定義書だの外部設計書だのをフォーマットにしてるわけだけど、ただ書くことが決まってるから埋めるだけ（で、大事な要件が漏れる）のSEをどうするか問題が出るわけよね

[roshi]

とりあえず句読点は、。で統一して書いて欲しい。

[manhole]

“ドキュメントで何よりも先に伝えなければならないのは「なぜつくったのか」「何を実現しているのか」「どう使えるのか」である．”

[luccafort]

“ともすれば何が解決困難な課題だったかとかどこに工夫を凝らしたのかといった “苦労話” を詳細にしたくなってしまうけれども，そういう話を初見の読者にいきなりしても何も伝わらない”あ、はい。すみません。

[rryu]

ドキュメントを書かなくても評価は下がらないが、下手なものを書いたりそのせいで仕事に時間がかかったりすると評価が下がるという完全にやったもの損な状況をまず変えるべきだと思う。

[gfx]

“我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか”

[toritori0318]

良い。自分がドキュメント書くときに意識してるのは「何も知らん人が入ってきたときに質問されずにすんなりプロジェクト開発できる」ようにしてることかな

[syu-m-5151]

コードには How テストコードには What コミットログには Why コードコメントには Why not 。では、ドキュメントには？

[yatmsu]

ほんとこれ。

[kazkaz03]

社内wikiがよく失敗するのと同じことだと思う

[seal2501]

概ね同意なんだけど「why/why not」はコミットログやPRやissueにも書き込めるしVS codeで辿れるので、雑なIssue/PRをリジェクトすることから始めるのが気楽だと思ってる(ただしメンバーからは嫌われる

[takilog]

テレワークで人間は意外と文書書けないし読めないってのが分かってきてるから、こういうのはかなり難しいなって感想。背景目的みたいなのすら書けない、読めない事例が多数。

[bootJP]

Design Docっぽい “論文のAbstractとIntroductionにあたる部分が必要だと考える”

[shag]

最近齢10年強の古のコード読みふけってるけど、ドキュメントに why, why not を書かない人は本当に多い。そしてクッソ古いドキュメントが放置されてたり、すでに通らないコードブロックが残ってたり。

[pmint]

それは取説でしょ。ドキュメントを知らない。文章もひどい。実務経験なさそう。この投稿をレビューしてもらうべき。必要なのは「どんな要求があったか」「どう作ったか」「なぜその手段（ロジック／UI）なのか」だ。

[marmot1123]

大事なことは分かっているけど、ドキュメントを書くのは（読むのも）疲れる。

[ema_hiro]

いい話。スタンスとして「固執する」くらいでちょうどいいのかもしれない。コードからは「何をしてるか？」はわかるが「なぜしてるか？」はわからないわけだし。

[yoiIT]

“どうして人間集団はこんなにも知見の共有を円滑にできないのか？ ”

[thaim]

何言っても書かない人は書かないので、自分のために書く。ドキュメント書かずに設計できないし、1年後に自分が困るだけなので。チームで書くようになるには報酬設計から考えないといけないので大変

[knok]

code2textは研究はされてるけど、当然ながらコードレベルの解説しか出力しない。教師データもdocstringとかだっりするし

[HM_Atlas]

“どうして人間集団はこんなにも知見の共有を円滑にできないのか？ “ / これオブこれ

[kei_0000]

上の立場は書かせたいけど、エンジニアは書きたくない（苦手＆面白くない＆自分がそこまで困らない）。レビューとか以前にまず書いてもらうことが大変。評価に含めるのもよいが、採用面談時に質問して見極めたい

[pascal256]

確かにドキュメントに経緯や意図を書くのは大事。パラメータ値とかも理由がわからん事あって変えれなくなったりするし…

[dal]

ドキュメント書いてもなーー読まれねえんだよなーーーほんとーーーーゴロゴロゴロそして書き手が途中でやめる。読んでくれさえすれば理解できる人たちなのにな。

[damasareta]

これは名言。「そもそも対人コミュニケーションというものは “厖大な知的体力と時間を奪われ，ペイロードではなくメタデータの比重が大きい，デフォルトでかなりの損害をもたらす営み” だ．」

[onesplat]

6. 変化が激しすぎて書く側からoutdatedになっていくため。4. 時間が取れないの見積もりが静的で甘い、ということでもあるかもしれない。追従チェッカも技術的/UX的になんとなく非現実的そうではある

[taitoku]

コード書く以外も高度な仕事があるって事だね。

[jintrick]

抽象化能力がないと書けない。残念ながら特殊能力に近い。

[Nnwww]

包括的でいい文章！個人的には開発プロセスに明示的にドキュメンテーションとそのレビューを組み込むべきだと思っている。何らかのプログラミングには対応するドキュメントの追加or修正をほとんどの場合含むはず。

[nakag0711]

長年の業界経験から言って、大半のエンジニアに文章作成力は期待できぬ。Excel方眼紙の跋扈もこれに関係があって、短文しか書けないからああいうのを好む