技術文書の書き方

howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。

[syu-m-5151]

ドキュメンテーションはテストと同じくソフトウェアエンジニアリングという領域の基礎をなすものだと確信しているのですがこのドキュメンテーションに関する文章は圧倒的に良すぎますね...

[dh16t]

mdとかで書いておくとコードと同じように管理できるから強い。図の管理は課題だったがvscode+draw.io integrationが良すぎて解決した。

[Tomosugi]

「技術文書」よりもっとしっくりくる呼び名が欲しいところ……technical documentのtechnical はcreativeやliteratureと対をなすものだから「実務」ってことだからね

[programmablekinoko]

いいね。HW,特にチップのデータシートとかも参考になる。

[CLSmooth]

“Architectural Decision Records (ADR)”

[tmatsuu]

すばらしい

[tune]

Protobuffet知らなかったので嬉しい。

[roshi]

GitHub Flavored Markdownというかプレビュー機能にVSCodeが追従してくれれば書く方も見る方も1アプリで済んで楽なんだけどなー。

[kappaseijin]

“ツール”

[nabinno]

私はPlantUML派。シークエンス図、アクティビティ図、ユースケース図、クラス図に加え、コンポーネント図まで扱えるからMermaidとdraw.ioでやりたいことは大方PlatUMLで片付く。

[aox]

全部7775調で書けば歌えるのでは

[asuka0801]

Design DocsとADRの使い分けいつも迷う。大体Design Docsに全部ババーッと書いてしまう事が多いなぁ。

[nilab]

技術文書の書き方 · GitHub

[mizdra]

網羅性高めるためには自動生成しましょう、なるほど

[Nyoho]

「mdBook: Rust 製 static site generator。高速でビルドできて見栄えが良いです。」

[kazokmr]

ちょっとした図を書くときにmiro使うんだけど、文書化には適さないなと思ってたので、ここに書かれているツールを試してみようかな

[conp]

“independent ”

[yasu-osu]

この文章自体が読みやすくて、とても参考になりました。おすすめです。

[awawawann]

とてもよい

[media56a]

技術怪文書の書き方に見えちゃった

[asa_ca3]

Excelが出てこなくて安心した

[BaramakiFPS]

ドキュメント管理の参考として

[dorapon2000]

“外部仕様書の類は、網羅していることと正確であることが大事。自動生成を第一の選択肢に。”

[inductor]

良くまとまってるなー便利だ。

[peketamin]

新しくなんかやるかと思って2年前に友達とやったプロジェクトを覗いたら、何を念頭に置いてたかもすっかり忘れてて焦ったけど、残しておいたドキュメントを読むことで思い出せた。WhyとかIF設計とか残すの大事。

[razokulover]

mermaid便利

[atsushieno]

最近流行りのAreWeYetは入ってなかった。

[tadyjp]

よいね

[yarumato]

“新規にソフトウェアを書き起こすときには、必ず設計文書を書く。 設計文書には、最低限「解決したい課題とその背景」「実装することになる予定の機能」「実装方針」を書きます。”

[IGA-OS]

そろそろワークフローもしてdrow.ioを組込んでみるかなぁ

[everybodyelse]

これは良いやつ