技術文書の書き方を読んだ

技術文書 = 技術記事かと思ったがそういうわけではなく、技術的な色々な文章についてということだった。

自分はドキュメンテーションが得意ではないので、この記事を読むと身が引き締まる……。

意外だったのは、「Design Doc は自分のため、メモはチームのために書く」というところ。

自分は逆なのかと思っていて、自分のためにメモを残してチームには Design Doc を書いて読んでもらうという感じかと思っていた。

まず、Design Docs は自分のために書き出すことが多いです。あとからチームの人が参照できはしますが、まず第一に自分がこれから作るソフトウェアのための準備作業の側面が非常に大きいです。

なるほどな。自分の思う Design Doc はちょっと違っていたのかもしれない。

書くこと以上に大事なのは、ソフトウェアの修正に伴って文書類をメンテナンスすることです。この点で、ソフトウェアの細かな内部仕様に基づいた文書を手書きすることは、一般的に良いアイデアとは言えません。

メンテナンスができない文書は、場合によっては削除してしまったほうがましだったりもします。

文書もメンテナンスをしやすくしていきたい。