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

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

おさえたいポイント３点

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

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

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

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

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

タイトルと概要とは

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

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

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

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

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

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

1, ネクストフューチャーアーティストとTikTokの関係性
2, 次に流行るアーティストとTikTokの関係性
3, 次世代アーティストとTikTokの関係性
4, 次世代アーティストとTikTokの流行の関係性
・
・
・

2.タイトルの内容をネットで検索してみる ネットで検索したらどんな言葉が出てくるかをみてみると、新しい言い回しが思いつくことがあります。また、似た内容の記事を書いている人が、どんな言葉を使っているか参考にすることもできます。

3.第三者にその文をみてもらう 何も考えずに読んでもらうことが重要です。そうすることによって、固定概念に縛られない、読者に近い感覚の意見がもらえます。

3. 規則性を持って話題の順番を並び替える

一通り記事が書けたら、話題の順番を見直します。読者のわからないポイントを貯めないために、順番はとても重要です。時系列、粒度、重要度などの並び替える方法があります。どんな方法でも、読者の立場を考えて書くことが大切です。

• 初めて使うときだけに行うこと
• 日常的におこなうこと
• 時々行うこと

といった、読者の必要なタイミングによって整理すると、どの方法で並べるとよいか、考えやすいと思います。

並び替えをしたあとは、

• 主張がまとまっているか
• 勘違いしにくい文章か
• １つ上の階層を正しく理解できていることが前提になってないか

など、誤読が発生しない構造になっているか確かめましょう。

まとめ

今回は技術ドキュメントの書き方をまとめました。上記の内容に気をつけて、技術ドキュメントをどんどん書いていきたいです。

参照

LINE Technical Writing Meetup https://youtube.com/playlist?list=PL80ip6bOwQsIfO757li02S42XDdWdnmED