ソフトウェアドキュメント作法 - maru source

こんにちは丸山@h13i32maruです。つい先日、devchat.fmというポッドキャストに出演して、「ドキュメント」というお題について話しました。なぜこんなニッチなお題について話したかというと、Ubie Discoveryに入社して5ヶ月の間にいくつか*1まとまったソフトウェアドキュメントを書いたので、自分の中でホットな話題だったからです。 #devchatfm 33回目は、Ubie DiscoveryのSWE @h13i32maru にドキュメントを書くことで得られるメリットや、ポイント・工夫などを聞きました！ #33 チームの生産性を上げるドキュメントのすすめ with@h13i32maruhttps://t.co/TrmZd13D91— 久保 恒太 / Ubie CEO (@quvo_ubie) 2021年8月12日 これらのドキュメントは個人的にわりと良く書けたと思ってますし、

[h13i32maru]

ドキュメントについての話題ってあまり見かけないので、自分で考えて書くしかないんだよな〜

[a-kuma3]

「スナップショットと割り切る」はダメだろう。そもそもがコードだけじゃキツイからドキュメント欲しい、なのに、コードと一致してないドキュメントはゴミ以上に害悪。RoIなんて言ってないでコストをかけろ、ってこと

[peketamin]

"今回はソフトウェアやシステムの内部構造を説明するドキュメントについての話です"/受託とtoC向け自社製品では事情も違うと思うし、いいと思います。

[ardarim]

ドキュメントの定義が世間一般と乖離している気がする。一般的にソフトウェア開発におけるドキュメントとは設計資料であって、説明資料、説明書ではない。ROIとか言ってる時点で見ているものが違う

[korilog]

少なくともその時点で正しいドキュメントはあったほうがいい。なんでこうなっているのかをコードの歴史から推測するよりドキュメント読む方が早いし。そもそもコードを読む理解を助けるものを書くイメージ。

[hitotakuchan]

ドキュメントの無いソフトウェアはいずれ必ず負債になる

[ed_v3]

可能な限りjsdocとかコード内に書けるもののみに留めてる。それ以上必要になったら全部ARCHITECTURE.mdに書くように最近はしてる。そして必要に応じてコード内コメントでARCHITECTURE.mdのセクションにリンク貼って更新忘れ防止

[shioki]

“ドキュメントを書く理由は人によって様々かもしれませんが、僕の場合は「ドキュメントにより、そのシステムをスムーズに理解できて、コードの読み書きを効率的にできるようになるため」です”

[jacoby]

（コード担当者が他者とコミュニケーションするための）外部仕様書はコードと一致してないと仕様不良とプログラム不良の判断できなくなる。内部仕様ならドキュメントよりコード読めになっても仕方ないとは思う。

[nunulk]

"読む人がほぼほぼ知ってそうなレベル、わかりきってるレベルから書き始めます。"

[tpircs]

文中にも記載あるけど、ドキュメントの肝は抽象化だよね。抽象的なコードを書くのは難しいので図や絵で表現する。そのほうが人類には理解しやすい。なので設計書は文章もいいんだけど図とか絵が大事だと思ってる。

[vine_hate]

ドキュメント

[Itisango]

社内のSWEにあまり実装経験が無いようなシステム/事業ドメインのコアでいろいろなSWEが触るようなシステム/世間一般に情報が無い社内独自のシステム

[ema_hiro]

わかるなーと思いつつ、こういうのも試行錯誤なんだよなー、というお気持ち。ちょうどいい塩梅が難しい。

[clockwork9]

最適なドキュメントの詳細度は組織次第。適切なスキルかつ同一文化圏のエンジニアが揃い、プルリクエストのレビューが機能しており、かつ完全内製の自社サービスの前提なら記事に同意。

[vndn]

スナップショットと割り切るところはいいとしても、読んだ人が直すって手法に不安が残る。読んだ人が気づいた乖離のみ直されるわけで、結果どの時点のスナップショットとしても正しくなくなるように思う。

[sigwyg]

ドキュメントには設計や実装理由を書けば陳腐化しにくい、てのは確かに／“ソフトウェアエンジニア（以下SWE）”　SEじゃないのん？Wが気になって夜も眠れな（ry

[tg30yen]

＞スナップショットだと割り切る これでいいと思う。「この時点ではこうだった」は現在のシステムを理解する上でも十分有用だよ。常に最新にアップデートされていなければ役に立たないなんてことはない。

[pmint]

ドキュメントが実装に合わせる側（主従関係の従）なのかな。「コメントの集まり」って感じか。本来は実装に守らせることを書くものだけど。/ 「コードに書いてあることは書かない」と言えば分かりやすくなると思う。

[kagerou_ts]

スナップショットと割り切るのは、原則的には今と違った情報乗せてしまっていてだめかもしれないけど、どのみち更新されず古くなる率高いのだから現実的な対応なのかも。そこが一番コストバランスよさそうとは

[ledsun]

2010年頃までは受託開発で、ドッチファイルに挟んだドキュメントを納品していた。あれは、ソフトウェアを理解する助けにはなってなかったろうなあ…

[diveintounlimit]

抽象度が高すぎて、これに則って書かれた「ドキュメント」を読んで何かを理解できる気がしない

[KazuoLv1]

ソースがドキュメントです。と真顔で言われて過去に辛い思いをしたなあ。インターフェースと簡単なサンプルあるだけで全然違うのに。

[w1234567]

当時の人がどういう意図で設計を進めていたのかが分かるから多少古くても問題ないよ。というか、コロナ化のリモートワークではドキュメントいらない勢はトラブルメーカーになってる人が多いからもう少し自省してくれ

[strow0343]

そのメンテ意識なら基本的に実装見に行くのが一番早い。ドキュメントは実装の理解の補助程度に落ち着くと思う。

[moromoro]

スナップショットと割り切ってしまい、ベンダ納品ドキュメントをメンテせずに動いてるサービスが多い

[tokg]

に

[naskin]

]

[kenzy_n]

ちゃんと意図の伝わるものが望ましい