KDOC 71: KDOCエントリの書き方

• 作成
  • 2024-02-04 貴島
• レビュー
  • 2024-02-08 貴島

本ドキュメントシリーズの記事の書き方をまとめる。

テキストで伝えるのは難しい。口頭でのコミュニケーションと異なり、時間的・空間的に離れている。読み手に正確に伝えるためには、多くの労力と経験が必要になる。自分で書いた文章でも、当時何を考えていたのかわからなくなることがよくある。自明だと思っていたことを端折っている。ドキュメント作りの難しさはそこにあり、自分が当然と考えている部分と向き合う必要がある。

このドキュメントの目的は、テキストコミュニケーションが持つ難しさを乗り越えるためのチェックリストを提供することである。

記事全体をどう構成するかは、解説する内容や目的（情報の要約、チュートリアルなど）によって異なるが、おおむね以下のようになる。

1. 概要

   ドキュメントの簡潔な要約を書き、読者がそこを読むだけで内容をすぐ把握できるようにする。自分があとから大量の文章から読み直すうえでも重要になる。先に要約を書くことで、記事のスコープから外れることを防ぐ効果もある。

2. 何のために記事を書くか

   問題意識を読者と共有する。何が問題かを示したうえで、その問題をどう解いていくかの筋道を示す。最初に明確なゴールが示されていると、理解しやすい。

3. 解説の前提となる情報の整理

   読者を記事の土俵に上げる。頻出の概念があれば明確な定義について書く。読者が知らないことを解説するというよりは、ドキュメントでの用語使用を明確にするため示す。

4. 主たる解説

   それぞれカテゴリに分けて章立てしていく。書く内容によってはさらに構造を深くしたほうが読みやすくなる。しかし、構造が深くなると読者が迷子になりやすいため深くしすぎないように気をつける。本ドキュメントシリーズではでは原則として1段階までとする。

5. まとめ、練習問題、関連情報、参考資料など

   より深く知りたいときのネクストアクションを用意する。

文書にステータスの章を設け、管理する。それぞれのステータスに対応したアクションを行う。

1. ドラフト

   作成中を示す。構成と文章作成に取り組む段階である。

2. レビュー

   作成が完了しレビュー中(推敲中)を示す。レビューステータスに進むためには、必ず一度ブラウザに出力して読みなおす必要がある。作成はテキストエディタで行っているが、ブラウザで見るとまた違って見えることが多いため。また、作成者とレビュー者が異なる場合、作成完了とレビューは少なくとも1日程度時間をあけるのが望ましい。文章の出力体裁と時間を空けることで、レビューに必要な文章との「距離」を取り、意味のあるレビューができる。

3. 完了

   レビューの推敲が完了し、作成完了を示す。今後修正することはあるが、文章として長期間の公開に耐えうるものである。

4. 廃止

   エントリの内容が古く、新しいエントリに置き換えられたのを示す。似た内容のエントリがすでにあるが大きく編集する必要があったり、主張が異なる場合は古いドキュメントを廃止ステータスとし、新しいエントリを作成する。ほとんどのエントリはこのステータスに移行しない。

図は強力なツールなので、積極的に使っていく。数千字かけるより1つの図ですぐ理解できることは多い。他人が理解しやすいだけでなく、自分が本当に理解しているか試せる。

• SVG形式で保存しているとあとから図を編集でき、Git管理もできるので楽である
• 参考になるYouTube動画は通常のリンクではなく、iframeで掲載すると画像も表示できるので積極的に使う

後で意味がわかるように、図や表を使った場合必ずキャプションをつける。図のキャプションがないと何をしたい図なのかわからないことが多い。

段落を使うときは以下の2点に注意する。

• ある段落を1つ取り出したとき、その内容を簡潔に要約できるか
• 段落と段落の関係は、全体として伝えたい内容にとって適切か

段落は次の要領で記述する。

• 空行から次の空行までの文章が、1つの段落になる
• 途中で改行しても、新しい段落にはならない

段落内および段落間をうまく構成すると、言いたかったことが伝わりやすい記事になる。レビュー段階で各段落の内容を自分で要約しながら自分で読み返す。

段落の主張を見やすく整理することを目的として、必要に応じて箇条書きを利用する。

箇条書きは図と同じく強力なツールであるが、文脈を不明瞭にする可能性がある。リスト同士の関係性が曖昧になりがちである。深さの違いは何か、並列にした理由はなにかは明示されない。箇条書きは段落とセットで使い、箇条書きのみで説明が終わらないようにする。箇条書きには、連番がつかないものと、つくものがある。それぞれ以下の要領で使う。

• 箇条書き（Unordered List）

  基本的には連番なしの箇条書きを使う。

• 項目1
  • サブ項目は1階層のみ可
• 項目2
  1. 連番つき箇条書きのサブ項目の例
• 連番つき箇条書き（Ordered List） 項目間の順序に意味がある場合や、あとから番号で参照したい場合は、連番つき箇条書きを使う。
  1. 項目1
  2. 項目2

テクニカルなドキュメントで、プログラムの一部を示したコードブロックは主要な解説対象である。したがって、コードブロックを提示するだけでなく、そのコードについて日本語で説明を書くようにする。具体的には、次のような内容を説明する。

1. なぜ本文のこの位置でそのコードを提示するのか
2. 何を実現するコードなのか
3. コードの各部にはどのような役割があり、どのように動作するか

プログラミング言語のコメント機能を使ってコード中に動作の説明を付記するのは、上記のうち3のみにする。コメント機能によるコードの動作の補足説明は、コードの中身をしっかり読む段階にある読者にとってはとても有用だが、初見ではあまり読まれない。特に上記の1と2の内容については、本文でしっかりと解説するようにする。

各文章レベルの細かなワーディングによって、読みやすさは大きく変わる。考慮することを示す。

• 体言止めを使わない

  動詞がないため何を指しているのか曖昧になるため避ける。また、読み手に負荷をかけるので使わない。

• TextLintルールに従う

  句読点のつけ忘れなどを防止できるほか、長過ぎる文、主格の連続使用など一般的に読みにくいとされる文章を検知できる。

• 優先順位の低いことは脚注に書く

  優先順位が低いが書かなければならないことは脚注に書く。逆に重要なことは脚注に書かない。脚注の内容を全く読まなくても問題ないようにする。

• タイトルの形式は KDOC N: xxxx 形式とする
• タイトルはエントリの内容を端的に示すものにする。内容の変化に応じて変更する

• 記事の書き方。ラムダノート社の素晴らしい解説。参考にした
• RFC Editor。ドキュメント作成のプロセスや体裁に関して、RFCを参考にした

• KDOC 78: org-modeで脚注を再割り振りする
• KDOC 161: KDOCの目的
• KDOC 166: KDOCは何ではない
• Insomnia