休日更新の備忘録

休日のみ更新予定の個人的備忘録置き場

【備忘用】エンジニアのためのドキュメンテーション

【目的】

 本記事は、エンジニアであり文章力のない著者が業務上でドキュメントを作成する際に意識すべきことを
 忘れないために記事にまとめます。

【はじめに】

 本記事は随時更新していく予定です。
 記事の内容に不備や「もっとこうした方がいい」等が多く発生するかもしれないですが、ご了承ください。

【大前提】

 この章では、ドキュメントを作るときに絶対に意識してほしいことを記載します。

読み手を意識する

 一番最初に意識すべきことは、「読み手を意識する」 です。
 ドキュメントは多くの場合に読み手がいます。
 提案書であればお客様、社内文書であれば社内の人間、自分のための備忘録であれば将来の自分。
 そして、ドキュメントの価値を決めるのは誰でしょうか。
 これは書いた人ではなく「読む人」です。
 どれだけ書き手がいいドキュメントや文章を作れたとしても、読む人が理解できない用語ばかり書いてあったら
 評価されません。
 前提知識に差がある場合も多く、読み手を効率よく納得させるためにも、読み手を意識して作るようにしましょう。
 また、ドキュメントが完成したら、自分の気持ちをリセットし、読み手の気持ちになって読み返すようにしましょう。

最初に目的を明確にする

 次に意識すべきことは、「最初に目的を明確にする」です。
 みなさんはドキュメントの初めに目的を書いていますか?
 どのようなドキュメントでも、物事を説明したい目的があるはずです。
 目的を最初に明確にしておくことで、ドキュメントを作るときは伝えたいことがブレにくくなります。
 また、ドキュメントを読むときは読み手が意識すべきことが明確になっているため理解しやすいドキュメントになります。
 ドキュメントを作るときは、書き手や読み手が無駄なことを意識しなくてよくなるよう最初に目的を明確にしておきましょう。

【初級編】

 この章では、ドキュメントを作成する際に誰でも意識すればできる「マナー」のようなことを記載します。

「です。ます。」調や「だ。である。」調を統一する

 ドキュメント内における文末は、「です。ます。」調か「だ。である。」調で統一しましょう。
 文末にこれらの調が混在していると、ドキュメントのまとまり(統一感)がなくなります。
 どれだけ重要なことやいいことが書いてあっても、評価されなくなります。
 文末を「です。ます。」調と「だ。である。」調のどちらを使うかは、ドキュメントを作る前に決めておきましょう。

ドキュメントを開いたときの表示位置を考える

 Excelのドキュメントを開いたとき、下の方で開いたことありませんか?
 Excel等は最後に保存した位置も保存されます。
 関係ないシートやシートの最後の方では保存せず、読み手に見せたいシートの先頭にフォーカスを設定して保存しましょう。

印刷設定を設定しておく

 近年では環境を考慮しペーパーレスと称して、電子ファイルを印刷することは減ってきています。
 それでも紙でドキュメントを提出することは多くあるでしょう。
 印刷者に負担をかけないためにも、ドキュメントの印刷範囲やヘッダー、ページ数等の設定は作成時に設定しましょう。

【中級編】

 この章では、ドキュメントを作成する際に意識したいことを記載します。

結論を先に記載する

 日本語は「・・・は○○○なので、×××です。」のように、長々と説明したうえで最後に結論を記載することが多いと思います。
 しかし、最後に結論を記載すると読み手に伝わりにくくなります。
 「・・・は×××です。それは○○○だからです。」というように、先に結論を記載して、次の文に理由を記載するようにしましょう。

見出しをつける

 大前提の「最初に目的を明確にする」に記載したことと被る部分もありますが、文章には見出しをつけましょう。
 「目的」以外にも、「結論」や「説明」等の見出しをつけることで、読み手は何について記載されているのかが
 文章内でも理解しやすくなります。
 何についての文章が記載されているのかがわかる見出しをつけましょう。

略語、俗語、専門用語を記載しない

 大前提の「読み手を意識する」に記載したことと被る部分もありますが、略語や俗語、専門用語を記載しないようにしましょう。
 特に専門用語を記載する場合は、読み手が記載した専門用語を知っていることが明確な場合のみにしましょう。
 略語は正確な名称ではないためドキュメントとしての価値が下がります。
 俗語については、「バグ」は「障害」、「処理がこけた」は「処理が失敗(異常終了)した」等に一般的な用語で記載しましょう。  ドキュメントは書き手の知識を披露する場ではないので、正確な名称や一般的な用語で記載しましょう。