はじめに
本記事は、ドキュメンテーションやスライドを作成する際のポイントをまとめたものとなります。
本記事の対象者は以下のような方となります。
- 社内向けドキュメントを作成する必要がある人
- 勉強会向けにスライドを作成する必要がある人
- 同僚や上司に向けて技術的な説明を行う際の資料を 作成する必要がある人
第１ステップ：全体の構成を決める
「論理的」な文章を作成する
「論理的」とは
- 道筋が通っている
- 納得感がある
- 感情的ではなく、客観的である
などの様子を指します。
つまり「問い」に対して「書き手の主張」と「根拠」を述べることで、論理的な文章になります。
ドキュメントであれば「使用方法」という問いを書きます。
記事やスライドであればテーマに沿った主張（テクニックなどのノウハウ）を問いとして書くことになるでしょう。
論理的に書くために、最初に全体の骨組みを行うとよいでしょう。
まずは「起承転結」を意識する必要があります。
それぞれ以下のように考えてみましょう。
起：タイトル
承：「はじめに」
転：メインの文章
結：「まとめ」
起：「タイトル」について
ドキュメントの場合は「名詞＋について」や「名詞＋の使用方法」などの、パッと見て即座に理解できるものが望ましいです。
スライドや記事の場合は、もう少し工夫が必要です。
パブリックなものとして公開する場合、他者に読んでもらうことを前提としているはずです。そのため、多少目を引くような単語を入れるとよいでしょう。例えば、「記事内で取り扱うテーマ及び技術名＋その記事を読むとどのような状態になるのか」のような構成のタイトルにすると、読み手にも記事の意図が伝わります。
またアニメや漫画のパロディのようなタイトルも時に有効です。
ただしあまりにも過剰なワードを入れると誇大表現になりかねないので、注意してください。
具体例として、私がQiitaで書いた記事の中でも特にLGTMが多かったものを参考のため、掲載しておきます。
スライドの＋α
タイトルと共に日付や、発表者の名前をスライド内に記載してください。そうすることで、そのスライド内ではいつ頃の技術を紹介しているのかが一目でわかります。
参考事例として、私が以前作成したスライドの1ページ目を掲載します。
承：「はじめに」について
ドキュメントを書く場合、この項目は省略しても問題ありません。
ここではタイトルで掲げているテーマや問題について、補足説明を行います。これによって、読者は記事の中に求めている内容があるかどうかを判断することができます。
必要であれば、開発環境やターゲットとする読者層についても記載してください。箇条書きやテーブル表を使うと見やすさが向上します。
記事を見に来る＠「の中には早急に解決手法を知りたい方も多いです。記事のテーマによっては、解決手法をこのパートで先に紹介してしまうのも良いでしょう。ただし、細かい説明を後にまわすと読者が注意すべき点も見漏らす可能性があるため、必要な情報も解決手法と合わせて記載しましょう。
スライドの＋α
メインの内容の前に、自己紹介を入れると参加者の興味を引く効果があります。10～30秒ほどで済ませられる自己紹介用のスライドを試しに用意してみましょう。
盛り込む要素としては以下の中から選ぶと良いかもしれません。
- 名前
- Twitter ID
- 受賞歴
- 社歴
- 趣味
- 興味のある技術
- 好きなIDE
転：メインの文章について
ドキュメントの本文や、テーマに対する解決手法の詳細をこのパートで記載します。文章を書くためのポイントは後程紹介します。文章以外で気を付けるポイントとしては以下のものがあります。
- 長くなりそうな場合は、更に小題に分ける
- 重要な説明を先に持ってくる
- 可能であれば図やイラスト、実例を入れる
- 参考プロジェクトがある場合は、それを載せるのもあり
スライドの＋α
技術的なテーマでスライドを作成すると、どうしても1ページに色んな内容を詰め込みたくなります。その気持ちをぐっとこらえて、1ページあたり、口頭説明をする時間も考慮して、長くても1分20秒ほどで説明できる内容にしてください。1ページ内に文字を多く書きすぎてしまうと、文字を小さくして詰め込む必要が生じる可能性があります。文字の読みにくさは、そのまま資料のわかりづらさにも直結します。本文の文字の大きさは最小でも24ptとし、行数のMAX値は6行としてみてください。この設定でスライドを作成した場合、1スライドに詰め込める内容は1つの細かな説明や、結果だけとなるでしょう。それくらいの方が、聞いている側にとっては一度に入ってくる情報量が少なくなり、理解が進みやすくなります。
また各スライドには、見出し部分にスライド内で説明している内容のタイトルを記載してください。スライド内容を理解する助けになります。スライドの後程スライドをアップロードした際も、必要な情報だけを探したいときに役立ちます。
以下にスライドで設定しておきたい内容をまとめます。
- 文字の大きさは最小で24pt、タイトルや見出しであれば36pt
- 1スライドに1つの説明、1つの結果
- 各スライド内に見出しをつける
- 行間は1文字の0.5倍の幅
- 行数はMAX 6
- 1行辺り、長くても40文字前後を目安に
尚、フォントに関しては以下が私個人のおすすめです。
| 項目 | フォント |
|---|---|
| 本文 | メイリオ、Meiryo UIがスタンダード。游ゴシックもモダンに見える。 |
| 英字 | Segoe UIがオススメ |
| コード | Consolasを使用すると判読性が増す（Iとl、Oと0など）。 |
結：「まとめ」について
テーマに対する重要なポイントを最後にまとめましょう。箇条書きにしても良いですし、文章でまとめても良いかと思います。
ここで参考にした書籍やサイトのURLを紹介すると、読者にとってはサンプル数が増えるため、喜ばれます。余裕があれば是非載せてみて下さい。
スライドの＋α
スライドの最後は「ご清聴ありがとうございました」や「質問や感想が御座いましたらご連絡下さい」といった文言で締めるのが良いでしょう。合わせて連絡先を載せておくこともおすすめです。スライドがきっかけで仕事の依頼問い合わせを頂いたり、他のカンファレンスに招待頂けることがあるかもしれません。
第２ステップ：とにかく書く！
最初から良い文章を書こうとして筆が止まってしまっては元も子もありません。長い文章を校正して、良い文章にすること自体は、そこまで工数がかかりません。まずは、文章構成のポイントに囚われず、自分の書きたい内容を一気に書いてしまってください。
第３ステップ：文章構成のポイントを掴む
文章を書く際には以下の点を考慮する必要があります。
1つの文に１つの内容
１文に対して複数の内容を盛り込まないようにしてください。
読者からすると、長い１文を読もうとすると脳内のメモリをフルに使うことになります。読者の負担を和らげるためにも、できればシンプルな文を書きましょう。
１つの文の中で、「～であり、」「～ため、」「～ので、」を用いると文量が多くなる可能性があります。伝えたいことが多くなると１文の中で全てを説明したくなりがちです。特に技術的なテーマの場合は、書き手が伝えたい情報量が多くなり、文も長くなるかもしれません。先述した文を繋げる語句を使うのではなく、区切って短くするよう心がけましょう。
文を書き言葉に変換する
以下のサイトのような書き言葉に関する解説しているサイトを参考にしてみてください。
記事を書く人の中には話し言葉を使用して、小説のように文章を構成する人もいます。
ですが、慣れないうちは書き言葉で統一してあげたほうが文章は読みやすくなります。
接続詞や副詞の言い方を変えるだけで、文章の読みやすさは変わるので是非試してみて下さい。ただし、不要な場面でも接続詞を使用すると、文がくどくなってしまうため削除する方が良いでしょう。冗長な文章よりもすっきりとしている簡潔な文章の方が理解しやすくなります。
二重否定文を使用せず肯定系の文を使用する
if文の条件式と同じで否定文を重ねるよりも、肯定文を使用するか、否定文は１つにする方が良いでしょう。「ｘｘｘしないと、△△△ができない」といった文よりも「ｘｘｘすると、〇〇〇ができる」の方がすっと頭に入ってきます。
「など」を使う時は具体例を後付けする
基本的には「など」を使わずに断定系を使用する方が、簡潔な文になりますが、使用したい場合には例として挙げた単語をまとめる名詞を最後に付け加えましょう。たとえば「枕や布団などは」で終わらせるのではなく「枕や布団などの寝具は」と言い換える方が良いでしょう。
ただし、目標やゴールを指す場合には、「など」は使用しない方がいいでしょう。使用すると曖昧な文になってしまい、読者に不安を与えてしまいます。それは避けるべきです。
鍵括弧や丸括弧の使い方を統一する
鍵括弧は以下に対して使ってみましょう。
- 固有名詞：「Zenject」「Unity」
- 人の発言内容
合わせて丸括弧は以下に対して使うと良いでしょう。
- 固有名詞の別名：ドメイン駆動設計（DDD）
- 品名や型番
補足情報を足す際に（）を使う人もいます。可能であれば、補足情報は本文から離れた箇所に記載をしてください。丸括弧は先述した箇所にのみ使用する方が統一感が出て読みやすくなります。
箇条書きは７項目まで
箇条書きは文章を要素ごとに分けて、シンプルに記載したい場合に使用します。あまりにも要素を多く書きすぎると、かえって複雑化し、読みにくくなります。もしも７項目よりも多くなりそうな場合は、要素をグループ分けして、複数ページにまとめる方が良いでしょう。
まとめ
以上、私が最近学んだテクニカルライティング手法に関して、まとめてみました。
大きいポイントとしては以下の通りです。
- 記事やスライドの全体の構成をざっくり決める
- 簡単な起承転結を意識してみる。場合によっては結果を先に持ってくる。
- まずはとにかく自分の書きたい内容を書く！
- 書いたあとに、不必要な部分を削減したり、文の順番を変えるなどの校正を行う
このような指針を持っておくと、本当に自分が注力したい箇所に時間を割くことができます。日頃から気にしてみると、徐々に文章を書く速度も上がってきますし、クオリティもアップしていきます。是非試してみて下さい。