技術文書の書き方
よく書かれる文書の種類
README.md
Design Docs
設計文書。
最低限書かれること。 - 解決したい課題とその背景 - 実装することになる予定の機能 - 実装方針
Specifications / API docs
仕様書。利用者にとって必要。自動生成できるツールがあるのが普通。
User guide
プログラムのマニュアル。網羅性よりは利用者が使うであろう機能を中心に実行例をわかりやすく書くことが大事。
Random memo
開発者のメモ。処理が複雑になった時など、他の人や未来の自分が理解しやすい形で解説する。このようなメモ類も大事な技術文書。
Architectual Decision Records (ADR)
なぜ、なにを、どう書くか
- ソフトウェアの修正にともなって文書類をメンテナンスすることが大事。
- 部や表は理解を促すのに大変重要。ツールも揃ってきているので慣れるのが大事とのこと。
ツール
- Markdown
- Mermaid.js: フローチャートを書くのに手軽に使える。GitHub上でmarkdown内でレンダリングできるらしい。
- draw.io
- mdBook
- Protobuffet
- Google Docs / Sheets
