(技術)文書を書く上で気を付けること

技術文書に限らないことだと思いますが、技術文書の書き方についてアドバイスを頂いたり、勉強会に参加したりしてtipsを得たので、箇条書き形式で書き留めます。
もちろんまだまだ網羅できていないので加筆予定です。
そもそもこの文章がイケてなかったらごめんなさいm(..)m
その節はご指摘くださいm(..)m

文書を書く際のtips

対象読者を絞る

どの前提知識がある読者を対象とした文書なのかを明記する。
絞らないと、前提知識がない人が読んで「全然理解できない…」となったり、書く側が前提知識を詰め込みすぎても冗長になったりする。
読み手・書き手お互いのためにまず絞る。

数年後の他人が読むことを考える

数年後に、自分が作成したプロダクトを全くの他人がメンテナンスするということは容易にあり得る。
例えば、知らない人が残したプログラムを動かそうとして、

• 動かし方がわからない
• どこに何があるかわからない
• 書いてある手順が読みにくすぎる

ことを経験したことはないだろうか。
もっと言えば私自身は、先週書いた自分の文章の意図や意味がわからないことさえある。書いている最中に頭の中にある前提や意図を明確に文章に記録しておく必要がある。

表記ゆれを起こさない

同じことを指しているのに、カタカナ・ひらがな・漢字、はたまたEnglishで表現してしまうことがある。状況や敏感な読者によっては、それぞれが違うものを指しているために、言葉を使い分けているのかと捉えられてしまうので、誤解を引き起こしかねない。

MarkDownを使う

これは個人的な意見だが、MarkDown形式を用いると、インデントや箇条書き、太字の機能が使いやすく、視覚的に優しい文章になる。
あとは、コードを貼る際に特に便利だなと感じる。

冗長な表現を避ける

細かいことかもしれないが、「〜ができるようになった」は「〜ができた」と書けるように、少しでも冗長化を避けることで、文章を簡潔にできる。

解釈の余地を与えない

言葉の選択によっては、その表現が複数の意味に解釈されることがあり得る。直接的な表現を避けるような、ザ日本人的な精神の癖が出るときや、自信がないときにやってしまいがちだが、特に技術文書を書く際には曖昧な表現は避ける。

作業手順は順を追って、過不足なく書く

とにかく手順やコマンドが知りたくて、ドキュメントを見ることはよくあると思う。
その中で、手順に出てくる事項の説明が手順の中に埋め込まれていて、読む気が失せたり、コマンドを実行するディレクトリの情報が抜けていて困ったことはないだろうか。
私はよくある。
そのドキュメントを読む人のニーズを考えて、過不足なく書き記していきたい。