ドキュメント作成時に意識すべき9つのこと！これであなたも「それっぽい技術ドキュメント」がつくれます

プロローグ

• 若手：「先輩、このドキュメント確認してください。どうですかね？すごく頑張ったんですけど・・。」
• 先輩：「うん、頑張ったね。でもなんか・・、チープに見えるなぁ」
• 若手：「え、なんでー！？ひどい！どこがダメなんですか？」
• 先輩：「うーん、表現が難しいんだけど・・・・なんか、プロっぽくないというか・・・、もっとそれっぽく見せる方法があるんだよ」
• 若手：「それっぽいって何ですか！？教えてください！！」

こんなやり取り、技術者なら一度は経験ないしは聞いたことがあるのではないでしょうか。

私も若手の頃は、一生懸命作ったドキュメントが「何が書いてあるかわからない」と先輩に言われて、ムカついた経験があります。でも、年を重ねた今では、先輩の言っていたことがよくわかります。

今回は、私が一子相伝で受け継いできた「それっぽいドキュメント」ができあがるためのノウハウを公開しちゃいます！

「こんなことも意識した方が良い」などのご意見がありましたら、コメントをお待ちしております！

はじめに

技術者は、日々さまざまなドキュメントを作成します。設計書、テスト仕様書、議事録・・・、どれも重要な資料ですが、ただ情報を羅列しただけのドキュメントでは、相手に伝わらず評価も低くなってしまいます。

タイトルにある「それっぽいドキュメント」とは、ただ情報が載っているだけでなく、読みやすく・理解しやすく・説得力のあるドキュメントのことです。

この記事では、私が長年培ってきた経験に基づき、誰でも実践できる「それっぽいドキュメント」を作成するための秘訣を紹介します。

ドキュメント作成時に意識すべき9つのこと！

① 作成対象ドキュメントが「スライド」なのか「文書」なのかをしっかり定義する

まず、自身が作ろうとしているドキュメントが「スライド」なのか「文書」なのかをしっかりと定義しましょう。

スライド（PowerPointなど）は、プレゼン資料として視覚的に情報を伝えるためのものです。簡潔な文章と図表を効果的に使用する場合はスライドを使いましょう。

文書（Wordなど）は、詳細な情報を正確に記録するためのものです。文章をしっかりと記述し、必要な箇所に図表を挿入する場合は文書を使いましょう。

ちなみにスプレッドシート（Excelなど）を方眼紙として使うのはオススメしません。ドキュメント完成後にPDF化する際だったり印刷する場合にページ表記が崩れたりしますので・・。やはり表計算のためのツールですから、スプレッドシートは表計算に使いましょう。

② 編集は複数人でできるように共有ツールを使い倒す

Googleドキュメント、Word、Dropbox Paperなどの共有ツールを活用することで、複数人で同時に編集できます。 コメント機能を使って意見交換を行い、より良いドキュメントに仕上げましょう。

イマドキのドキュメント作成はコラボレーションが肝です。それぞれ個人で作成したり、ファイルの回覧をしたりして、余計なマージ作業をすることがないようにしましょう。

③ドキュメントのスタイル適用を徹底する

フォント、文字サイズ、行間、色使いなど、ドキュメント全体のスタイルを統一しましょう。 会社やプロジェクトで規定されているスタイルがあれば、それに従いましょう。

もし、お使いのスタイルがない場合は、公式のテンプレートを使うのも手です。（Wordの場合、参考になるページはこちらです。）

もしくは、半日くらいかけてオリジナルのスタイルを作っても良いかもしれません。スタイルは1回作ってしまったら何度でも使い回せるので、時間をかける価値はあると思います。

Wordの場合、参考になる記事がこちらです。

④スクショ貼付頻度や記載粒度は世のクラウド公式ドキュメントにあわせる

複雑な操作手順などを説明する際は、スクリーンショットを有効活用しましょう。 しかし、何でもかんでもスクショを貼るのはNG。後で更新が大変です。スクリーンショットは必要最低限にとどめ、説明文とのバランスを意識しましょう。 とくに、AWSやGCPなどのクラウドサービスの公式ドキュメントを参考にすると、洗練されたドキュメント作成のヒントが得られます。

⑤構成図などの挿絵を作成する場合は専用のスライドファイルに保存

構成図やフローチャートなど、図表の作成はそれ専用の共有ファイルを作成し、ドキュメントに埋め込みましょう。 もし後から図表の編集が必要になっても、共有しておけば誰でもすぐに編集できます。あと、図表の見た目も統一できます。

⑥ 体言止め、ですます調、を統一

体言止め、ですます調の統一は徹底してください。

たとえば、タイトルは体言止めにすることで、簡潔で印象的な印象を与えます。 本文は「ですます調」で記述することで、丁寧で信頼感のある文章になります。

ドキュメント作成の際に決めてしまうのが一番良いですね。

⑦ 「下さい」→「ください」　「様々」→「さまざま」を使う

言葉遣いを意識することで、より洗練された印象になります。 正確な表現を使うことで、相手に誤解を与えません。

そうはいっても何か指標がないと難しいと思います。弊社では「記者ハンドブック 第14版: 新聞用字用語集」を参考にしています。

このハンドブックは世の中で一番文字を大切にされているであろう記者の方々が活用されているものです。私は最初に読んだとき、目からウロコでした。

⑧ 「 No 」→「 No. 」　「 Mr 」→「 Mr. 」　など略語のピリオドを省略しない

「No」や「Mr」のように、本来は省略形である単語は、正式な文書ではピリオドを省略してはいけません。

「No.」は「Number」の略、「Mr.」は「Mister」の略であり、ピリオドは省略形であることを示す記号です。省略形を省略することによって、意味が曖昧になる場合や、失礼な印象を与える場合もあります。

ドキュメント上では、正確な表現を心がけ、ピリオドを省略せずに「No.」「Mr.」と書きましょう。

⑨ 固有名詞は正確に。略称は宣言してから。

固有名詞を正確に表現することはドキュメントの正確性と一貫性を維持するために必要なことです。とくに、専門的な用語や組織名、製品名などが含まれる場合、誤った表記は読者の理解を阻害し、信頼性を損なう可能性があります。

• 常に正確な表記を使用する。

  • 例：「マイクロソフト」ではなく「Microsoft」、「アマゾン」ではなく「Amazon」

• 複数の表記が存在する場合は、事前に統一された表記を決定する。

  • 例：「人工知能」と「AI」のどちらを使用するかを明確にする。

また、略称を使用する場合は、最初に登場する際に正式名称とともに宣言することが適切です。

• 例：世界保健機関（以降、WHOと表記）は、パンデミック対策を強化している。
  • 宣言した略称については、以降は一貫して使用する。略称が一般的でない場合は、その場で説明を加えることもあり。

おわりに

いかがでしたでしょうか？私は、何かドキュメントを作成する際は上記を心がけています。これが無意識にできるようになると、いつの間にか「それっぽいドキュメント」ができあがってきます。不思議です。

ドキュメントは人に伝えるためのものです。「読みやすさ」は重要なのだと思います。せっかく頑張って作成したドキュメントが使われない、ということがないようにしたいですね。

この記事が、あなたのドキュメント作成の参考になれば幸いです。

おしらせ

弊社X（旧：Twitter）では、Qiita投稿に関する情報や各種セミナー情報をお届けしております。情報収集や学びの場を求める皆さん！ぜひフォローしていただき、最新情報を手に入れてください