技術ドキュメントの書き方のコツ(初心者向け)

2022-07-25

この記事は最終更新日から1年以上が経過しています。

技術ドキュメントの書き方のコツ(初心者向け)

FY21新卒アプリ開発グループの塚本です。Androidアプリの開発に取り組んでいます。
技術ドキュメント初心者の私が、技術ドキュメントの書き方について勉強しました。
おさえたいポイント３点を中心に、まとめていきたいと思います。

おさえたいポイント３点

主語や目的語を明確にする
タイトルと概要を使う
規則性を持って話題の順番を並び替える

1. 主語や目的語を明確にする

登場人物が多いときに注意が必要です。日本語は意外と主語がなくても意味が通じてしまうときがよくあります。会話の中だと、疑問点をその場で聞いたり、相手の反応を見て補足することができますが、文面だとそうはいきません。
以下の３点に注意して、より分かりやすい文章にします。

名前（名詞）が何を指しているか確認
文を英語に翻訳してみるのも一つの方法です。I(わたし)の動作として書いたものが、You(相手)と翻訳されるときがあります。そのようなときは主語があやふやになっているときが多いです。
声に出して読んでみる
声に出して読むことで、自分の思考の中で勝手に情報を補足していないか気づくことができます。また、一文が長くなりすぎていないか確認することができます。
文を短くするとき、名前を捨てない
主語や目的語を省略対象にしないようにしましょう。

2. タイトルと概要を使う

タイトルと概要とは

タイトルは、ひと目で記事の内容を判断するものです。
一方、概要は、タイトルに続く文章のことで、タイトルの一言で書ききれなかったことを書きます。

なぜタイトルと概要が必要なのか

読者がわかりにくいと感じる原因の多くは、「読者が期待していた内容と記事の内容にギャップがある」ことです。タイトルと概要を見て、読者はこの記事を読み進めるかを判断します。適当なタイトルと概要をつけることは、必要な情報をスムーズに読ませるだけでなく、不要な情報を読ませない効果もあります。タイトルをより良くするには、タイトルにとって、一番良い１行を探すことが重要となってきます。

タイトルにとって、一番良い１行を探す

この方法はタイトルだけでなく、「この文章がピンとこない」「より良い言い回しがないか考えたい」といった状況でも使えます。方法は色々ありますが、今回は３つ紹介します。

1.コピペしながら全部の案を並べていく
模索していく中で、「さっき考えた案」を残しておいて、最終的に見比べられるようにします。
そうすることによって、いいとこ取りができたり、「さっきのほうが良かった気がするけど思い出せない」といったことがなくなります。案を並べていくなかでナンバリングをすると、どう変化してきたのかが分かりやすいです。
例)