ドキュメントに固執せよ - gfnweb
2022/06/18 11:41
sgo2
「コンピュータが期待する動作をするコード」と「人間が期待するよう解釈する文章」では前者の方が遥かに簡単に書ける。後者は個や状況で反応が変わり過ぎる。
2022/06/18 12:25
nunulk
"これらの情報が必要なのは,こうした情報なしにただ実装されたシステムのみに対面させられた人はそれを何らかの文脈の中に位置づけることができず,したがって今後開発が必要になりそうなことの検討などが容易に..."
2022/06/18 12:54
ai_gaminglife
プログラミング言語より自然言語のが難しい問題
2022/06/18 13:01
tettekete37564
コードを読めば何をやっているかは分かっても、何のために何でその実装なのかは分からない。つまり実装からその要件は分からないとという事。特にバグがあった時とかね。
2022/06/18 13:03
Nunocky
“ドキュメントが読まれない場合は,原則としてドキュメント自体にまだ問題があると思った方がよい” ほんとこれ。書いた人以外全貌を把握できないのは仕様書とは呼べない。
2022/06/18 13:06
poleight
"人間は自分の実装したものについて説明するとき,ともすれば何が解決困難な課題だったかとかどこに工夫を凝らしたのかといった “苦労話” を詳細にしたくなってしまう"
2022/06/18 13:29
Shinwiki
書くの苦手なやつが思ってるより多い
2022/06/18 13:39
Palantir
手順や準備のドキュメンテーションが予算として組み込まれてないから毎回新鮮な気持ちで仕事できる。*;“]^>]*]+\!\’]*[>\^_”_“_”“_‘_[!!!!!!
2022/06/18 13:54
for-my-internet-demo
はい
2022/06/18 14:20
kazukan
オフショア開発とかコミュニケーションギャップが大きすぎると大枠の概要は理解できなくて、よりコンピュータの動きを言語化したような詳細設計が求められる。小学生でも誤解されないように書くしかない。
2022/06/18 14:30
kaakaa_hoe
whatよりhow、howよりwhy、whyよりwhy not。記録残さないと後々変更する時に観点漏れるよね。
2022/06/18 14:52
nyankosenpai
人類の多くには言語化する力がないし、言語を読み取って行動することも苦手としているのだ。けっこうな特殊能力だと思います
2022/06/18 15:44
shikiarai
“ドキュメント追従チェッカ”小規模システムだったので、これを人力でやる手順を確立して後輩にも伝授して後輩も納得、理解してくれた。その後、全く活用はしてくれず、今はカオスになって、私に戻ってきた。
2022/06/18 15:46
hdannoue
ドキュメントは、言語で標準化された事象や現象は書きやすいし、共有性も高く、利益もある。しかし、バリエーションあることや複雑な構造は記述しにくいし、読み手に伝わりにくいので、コストに見合わない。
2022/06/18 15:59
oshishosan
上司がドキュメントに固執してくれないから…
2022/06/18 16:11
ch1248
同意できる。
2022/06/18 16:15
roshi
とりあえず句読点は、。で統一して書いて欲しい。
2022/06/18 16:19
puruhime
人間には連続性がなく、ドキュメントの読者は未来の自分だったりする。abstractの部分だけでも明瞭になってると、未来の自分から呪われる事は減るかもね
2022/06/18 16:34
atsuououo
自然言語はその人が持ってる文化をそのまま表すからね、下手に共通化しようとすると紛争が起こるね。
2022/06/18 16:42
naqtn
前提として読む能力や習慣が組織に必要。よりよく読む人じゃないと価値が分からないから書かない、書かないから質の良いものが書けない、読む価値のあるものが生まれない、という負のスパイラルががが。どうすれば…
2022/06/18 16:42
Great_Pizza
「分からないならドキュメントに全部書いてあるからそれ読んで」とエラそうに言われた後、ドキュメントの中身がスカスカで読んでも何も分からなかった時に湧き上がる悲しみと怒り。ちゃんと書け。
2022/06/18 16:59
theatrical
ドキュメントと会話の大きな違いは、会話は都度確認ができるので、相手に対して最初に想定した理解度とかが間違っていてもすぐに対応できること。ドキュメントは対象が多い上に、都度修正できないので難しい。
2022/06/18 17:19
takuver4
これ、個人開発ならともかく普通の企業なら当然のようにやってる事なんじゃないの?逆にやってない場合って、そもそもコードのメンテナンス不可能じゃない?
2022/06/18 17:19
hatsumoto
ほんっとに読まないよな!下手したら一回メンションした上でミーティング設定して口頭で耳から入れないとダメな人までいる。読めよ。
2022/06/18 17:29
hitotakuchan
ドキュメントのないソフトウェアは全て負債である
2022/06/18 17:48
cha16
歯車の仕様を書くドキュメントもあるだろ?歯車は勝手に動いていると思っているのか?致命的に頭悪いな。
2022/06/18 18:16
wwolf
何故こうしたのか?を記録してほしいんだけど、大抵「流行ってるのでやってみたかった」みたいなところに着地するので皆書きたがらないんだよね。深い理由が無いなら無いで別にええんやで。
2022/06/18 18:27
kkrsnsn
最近思うのは意味の通るドキュメントが書けるのは才能だってことだなぁ、多くの人は練習しても良いドキュメントを書けるようにならないみたい
2022/06/18 18:35
robamoto
予備知識の無い人間に理解できる文書を書くの、コードを書くのとは別の面倒くささがある
2022/06/18 18:46
yyamano
ドキュメントきちんと書いても、能力的に読めない人が多いと効果が出ないので、どこに労力を割くかは悩ましい
2022/06/18 19:00
remcat
腕時計の背景が何か使えそうなのでメモ
2022/06/18 19:06
moromoro
てんこ盛りすぎな気配
2022/06/18 19:18
MERCY
同意は出来るんだけど、コードは最低限動いてるから信頼できるのに対して、ドキュメントは嘘(過去の記述)が有るから、常時メンテしてて常に正しいドキュメント以外が混ざったらその時点で全てゴミになる
2022/06/18 19:23
programmablekinoko
確かに
2022/06/18 19:28
khss_keita
まず思い浮かぶのは、業務引継書。 この品質次第で、後任のパフォーマンスが大幅に変わり、モノが悪いと後任の評価までに影響しうる。ただ、引継書は基本ノーチェックだし、評価対象外なので真面目に書かない人も多
2022/06/18 19:34
tafutech
JTCはみんな書いてるよ。その代わり開発スピードがめちゃくちゃ落ちるけどね。
2022/06/18 19:44
midnight-railgun
腕時計の例で言うと、読者が置き時計を知っていないとこの情報のみから理解するのは困難だし、逆に知っているのであれば冗長だしで、やっぱりドキュメントって難しいなぁ
2022/06/18 19:49
tinklingway
何を目的に文書を書くのかって、ちゃんと押さえておかないと書けない。
2022/06/18 19:55
carrier_pigeon
ありがたい文書。why/why not がないと困る。次の dev も困るし ops も困る。ソフトウェアは運用フェーズがライフサイクルで一番長いし、嘘があるというのは更新プロセスを定義してないだけで書かない理由にはならない。
2022/06/18 20:06
xufeiknm
後進に教育する意思も能力もない集団にいたので、ほんとにこの文章の大切さが解る。漸く自分がやらないと誰もやらないことがわかってマニュアルを書き続けた20年だった気がする。
2022/06/18 20:13
akatuki_sato
論文を書く経験は大事よな。ただ、文章が長くて読みにくい。。。短くすると読みやすくなると思う
2022/06/18 20:25
yimajo
ほかコメントにあるような「ドキュメントは間違いが混ざるからゴミになる」みたいな意見はよく見るけどそれをやらない理由にされるのはただの怠惰。どうせ散らかるから掃除しないと言ってるように思える
2022/06/18 20:30
mayumayu_nimolove
情報が多すぎだから取捨選択してるだけ。無理やり覚える方法取っても無駄だから。
2022/06/18 20:37
ngmy
常に右肩上がりの成長を株主から求められ、いつまでも少数精鋭でいることが許されない資本主義社会が、ソフトウェア開発を過剰に難しくさせている気がする。
2022/06/18 20:40
masudatarou
実装の理由とかはslackとjiraとかbacklogみたいなタスク管理ツールに残されてるでしょ
2022/06/18 20:47
enhanky
意図や仕様はコメントに書いておいて、必要ならdoxygenとかでドキュメント単体にまとめるっていうのがいいのでは。物理的距離が近いのでコードに追従しやすく、gitでコードごと履歴管理ができて検証しやすい。
2022/06/18 20:51
ext3
こんなんいるん?
2022/06/18 21:16
ledsun
ドキュメントが書かれないのは、ドキュメントを書く能力がないから。ドキュメントを書く訓練が必要です。
2022/06/18 21:33
ya--mada
図で補っても構わないし、動画にキャプションでも良いので、経験を知識に落とし込んで共有して欲しいのよね。そのための訓練を大学で受けてきてると期待してるのだけどね……。
2022/06/18 21:51
xigemoto
関係者全員が同じ前提認識に立って、手戻り少なく本質的価値の実現に向けてプロジェクトを進めるために、ドキュメントは超重要。これも、リソース効率ではなくフロー効率的考えといえるか。
2022/06/18 22:28
princo_matsuri
UEのエンジンソースも末端の関数はコメント1行とかだったりで結局コードを読むはめに
2022/06/18 22:59
tpircs
カテゴライズ、グルーピング、レベリングがきちんとできる人って少なし、それが通じる人も結構少なかったりする。
2022/06/18 23:08
htnmiki
なぜか馬鹿にされがちな大手SIerの得意分野じゃないのかね
2022/06/18 23:36
comenegie
弊社技術は、一子相伝、口承により下世代へと引き継がれている。・・・などと上層部は供述している模様。
2022/06/18 23:45
sippo_des
今何十年も前の製品の情報を、いろんな場所から集めてるんだけど、なんで背景も知らない私がやらなきゃいけないんだろ。書いてないことは集められないんですよねー。やりたくないです。開発者とか企画がやれ。
2022/06/18 23:45
wacok
““仲良しチーム” になるのではなく,“相反する意見をぶつけ合っても根抵には相手への信頼がある” という状況をつくらねばならないからだ”
2022/06/19 00:01
Andrion
疎結合になるとプログラムの全体像が分かりにくいってことはあると思う。全体的な思想はドキュメントに残して、個別の工夫はコメントで良い。
2022/06/19 00:30
PrivateIntMain
why or why not は要件レベルでも実装レベルでも残っていると嬉しい/いきなり案件にぶっ込まれた人がよくわからんまま仕事進めて爆死してませんか?が主題で、ドキュメント以外で解決できるならそれに越したことは無い
2022/06/19 00:50
dreamzico
日本語の文章なのに句読点を使わずにカンマやピリオドを使っているドキュメントは読む価値がない。理系のお前ら、全員に言ってるんだよ。誰がその慣習やり始めたんだ。その読みづらくてクソみたいな慣習。
2022/06/19 01:42
ngsw
すき。突き詰めると採用(これは想定読者の定義になる)から地続きのものと考えている
2022/06/19 02:39
lb501
目的だけ依頼されて背景を聞いたら、実はもっと簡単な方法があるよと言う例がたくさんある。何故背景を話さない人が多いのか?
2022/06/19 02:47
nakag0711
長年の業界経験から言って、大半のエンジニアに文章作成力は期待できぬ。Excel方眼紙の跋扈もこれに関係があって、短文しか書けないからああいうのを好む
2022/06/19 03:32
choota
強いエンジニアは文章も書けるし、弱いエンジニアは文章苦手。強いエンジニアはそんなに数いないので、結果文章は置き去りにされる。
2022/06/19 03:42
Nnwww
包括的でいい文章!個人的には開発プロセスに明示的にドキュメンテーションとそのレビューを組み込むべきだと思っている。何らかのプログラミングには対応するドキュメントの追加or修正をほとんどの場合含むはず。
2022/06/19 04:37
jintrick
抽象化能力がないと書けない。残念ながら特殊能力に近い。
2022/06/19 06:33
taitoku
コード書く以外も高度な仕事があるって事だね。
2022/06/19 07:03
onesplat
6. 変化が激しすぎて書く側からoutdatedになっていくため。4. 時間が取れないの見積もりが静的で甘い、ということでもあるかもしれない。追従チェッカも技術的/UX的になんとなく非現実的そうではある
2022/06/19 07:06
damasareta
これは名言。「そもそも対人コミュニケーションというものは “厖大な知的体力と時間を奪われ,ペイロードではなくメタデータの比重が大きい,デフォルトでかなりの損害をもたらす営み” だ.」
2022/06/19 07:10
dal
ドキュメント書いてもなーー読まれねえんだよなーーーほんとーーーーゴロゴロゴロそして書き手が途中でやめる。読んでくれさえすれば理解できる人たちなのにな。
2022/06/19 07:55
pascal256
確かにドキュメントに経緯や意図を書くのは大事。パラメータ値とかも理由がわからん事あって変えれなくなったりするし…
2022/06/19 08:01
kei_0000
上の立場は書かせたいけど、エンジニアは書きたくない(苦手&面白くない&自分がそこまで困らない)。レビューとか以前にまず書いてもらうことが大変。評価に含めるのもよいが、採用面談時に質問して見極めたい
2022/06/19 08:10
kakei-akihiko
ドキュメント自体は有用なんだけど、未来にどこのバグが発覚するのかなんて分からないからドキュメント書いても結局バグは生まれる。
2022/06/19 08:34
smallpalace
そこまでちゃんとしてないけどとりあえず忘れっぽいので自分のためだけに書いてることが多いな。あとから検索して人に説明する前段で読んどいてもらったり活用できる。
2022/06/19 09:01
HM_Atlas
“どうして人間集団はこんなにも知見の共有を円滑にできないのか? “ / これオブこれ
2022/06/19 09:42
khtno73
だからSIerは要件定義書だの外部設計書だのをフォーマットにしてるわけだけど、ただ書くことが決まってるから埋めるだけ(で、大事な要件が漏れる)のSEをどうするか問題が出るわけよね
2022/06/19 09:47
knok
code2textは研究はされてるけど、当然ながらコードレベルの解説しか出力しない。教師データもdocstringとかだっりするし
2022/06/19 10:42
thaim
何言っても書かない人は書かないので、自分のために書く。ドキュメント書かずに設計できないし、1年後に自分が困るだけなので。チームで書くようになるには報酬設計から考えないといけないので大変
2022/06/19 11:22
xojan0120
日本語がだるすぎるからでは?
2022/06/19 13:05
yoiIT
“どうして人間集団はこんなにも知見の共有を円滑にできないのか? ”
2022/06/19 13:37
ema_hiro
いい話。スタンスとして「固執する」くらいでちょうどいいのかもしれない。コードからは「何をしてるか?」はわかるが「なぜしてるか?」はわからないわけだし。
2022/06/19 13:50
marmot1123
大事なことは分かっているけど、ドキュメントを書くのは(読むのも)疲れる。
2022/06/19 15:37
pmint
それは取説でしょ。ドキュメントを知らない。文章もひどい。結論から書こう。この投稿をレビューしてもらうべき。必要なのは「どんな要求があったか」「どう作ったか」「なぜその手段(ロジック/UI)なのか」だ。
2022/06/19 15:39
shag
最近齢10年強の古のコード読みふけってるけど、ドキュメントに why, why not を書かない人は本当に多い。そしてクッソ古いドキュメントが放置されてたり、すでに通らないコードブロックが残ってたり。
2022/06/19 19:17
bootJP
Design Docっぽい “論文のAbstractとIntroductionにあたる部分が必要だと考える”
2022/06/19 19:44
takilog
テレワークで人間は意外と文書書けないし読めないってのが分かってきてるから、こういうのはかなり難しいなって感想。背景目的みたいなのすら書けない、読めない事例が多数。
2022/06/19 20:41
seal2501
概ね同意なんだけど「why/why not」はコミットログやPRやissueにも書き込めるしVS codeで辿れるので、雑なIssue/PRをリジェクトすることから始めるのが気楽だと思ってる(ただしメンバーからは嫌われる
2022/06/19 23:57
kazkaz03
社内wikiがよく失敗するのと同じことだと思う
2022/06/20 00:16
yatmsu
ほんとこれ。
2022/06/20 08:45
syu-m-5151
コードには How テストコードには What コミットログには Why コードコメントには Why not 。では、ドキュメントには?
2022/06/20 09:33
toritori0318
良い。自分がドキュメント書くときに意識してるのは「何も知らん人が入ってきたときに質問されずにすんなりプロジェクト開発できる」ようにしてることかな
2022/06/20 09:45
gfx
“我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか”
2022/06/20 12:38
libra_x1
正しい。でも腕時計の事例からわかるようにこのドキュメントは自己満足だ。自分の気にできることばかり書いている。誰が腕時計のことを語る時に0-originを気にする?自意識の引き算ができない時点で未熟、説得力0
2022/06/20 16:17
rryu
ドキュメントを書かなくても評価は下がらないが、下手なものを書いたりそのせいで仕事に時間がかかったりすると評価が下がるという完全にやったもの損な状況をまず変えるべきだと思う。