エンジニアのドキュメント作成について理解はしているが手が動かない現象

Document作成について自分が現在思うことを書いてみる。

Documentといっても種類がたくさんある。

  • 手順書
  • 設計書
  • メモ(?)バッチとか一覧が書いてあるやつ仕様書に近い

documentを書くべき理由は自然と理解している人は多くいると思う。 なくてもやっていけるが、あれば物事がスムーズに進む場合がある。

例えば

  • 環境構築手順
  • インフラ構成図
  • よく使う便利コマンド一覧とかとか

ドキュメントの有無で作業のキャッチアップまでがとても早くなり次の行動への生産性が上がる。 入れ替わりの激しい所であれば再度同じ質問などを繰り返し聴かれなくても済んだりもする。
理解はしているがマジで書きたくない。でも書かなきゃな〜と思っている人に向けて感想を書いている。

自分が重要と思ったところは「書くべきところを決める」「書き始め方」「どう継続させるか/周りを巻き込むか」だと思う。

書くべきところを決める

さすがに全てのドキュメントを書くことはできない。そんなことをしたら鬱になる。

ドキュメント書け書け星人がいても、ドキュメント文化がない所だと書いたところで誰も見ないし誰も保守をしない事が目に見えている。文化があればこんな文章見ていない。

まず書くべきドキュメントを決める。

[使用頻度] / [めんどくささ] / [お金を生む量]

様々な解釈はあれば上記などで優先度をつけて書いていけばいいと思う。

コードのテストも似たような優先度でかけると思っている

お金を産んでないシステムはお金を産むことに注力して、お金を生み始めたらクリティカルな部分はテストで書いていくべきだろう。

リファクタなども同上

書き始め方

書き始める前に

  • どの粒度でまとめればいいのだろう
  • どのようなファイル・文章構成にすればいいんだろう
  • 読む人のことを考えると・・・あれも　これも・・・図も・・・

などを考えるといつまでたっても完成しない。

最初の人は軽く「これでいいやろ」の精神で書くべきだと思っている。

工数が許す限り補正すればいい

どう継続させるか

Documentも更新（開発）が必要である。

なぜDocumentだけは更新されないのか・・・

自分が思う理想の開発の流れは

案件の調査 -> Documentを見てそのモジュール周りを理解 -> 実装しながらdocument更新 -> リリース

documentがなく「書くべき所」であれば「これでいいやろ」で書けばいい。

最初の人は「これでいいやろ」の精神で書いているので、読む人の経験/知識レベルなどは網羅する事は絶対にできてない。

さらに当時の環境から差分は生まれているはずなのでドキュメントとの違いは出てくるはずである。

その実装者がdocumentに足りないと思った部分を継ぎ足してくれるだけでいい。もちろんこの人も「これでいいやろ」の精神で書く。

知識の差がすごいと書いてある事が理解できないので、理解しようと頑張る。(実装にもつながる)

かつDocumentに残す事で「言語化」もできるし、理解もさらに深まる。

素晴らしい。

そしてなぜ「実装しながら」なのか、実装終わった後に書こうとしても、基本忘れているしめんどくさくなるだけである。リリース手前まで来てドキュメントを書きたくなるだろうか？自分ならリリースして次の案件に着手したくなる。

しかし「これでいいやろ」精神で実装しながらなら、エラーが出たらエラー文をコピペして解決策のURLを貼るだけでいい。

この作業に5分もいらないだろう。この作業だけで助かる人がいるかもしれない。労力に見合っていると思う。

モチベ,巻き込み

わからないｗ Documentはソースコードとは別サービスなどで管理されている事が多く(?)、更新しても誰も反応してくれない。反応があるだけで結構モチベって変わってくると思う。

もしドキュメント作成を布教しようとしている人は書く人のモチベを上がる方法を考えて見てはいかがでしょうか

使うと幸せになるかもしれないツール