テキスト・正規表現
READMEが読みづらい。Markdownで手順を整理したい
使うツール
説明は全部書いたはずなのに、使い方を何度も聞かれる。READMEの問題は情報不足だけでなく、必要な情報へたどり着けないことにもあります。最初に長い背景説明が続き、実行するコマンドが文章に埋もれていれば、読む人はどこまで理解してから始めるべきか迷います。Markdownプレビューで原文と表示を見比べ、読者の最初の一作業に沿って並べ直してみましょう。
見出しは、装飾ではなく道案内にする
# Example Tool
A small example for checking a local text file.
## Before you start
Use a fictional input file.
## Try one example
Follow the steps below.
## If the result differs
Check the input and selected options.Markdownプレビューへ貼り付け、文書名が一番大きな見出し、その下に準備・実例・困ったときの節が並ぶことを確認します。文字を大きくするために見出しを使うのではなく、内容の階層を表すために使います。読み手が探す『最初に試す』『結果が違う』という用事を見出しにすると、すべてを最初から読まなくても必要な場所へ進みやすくなります。
節を増やしすぎると、一行ごとに見出しが付いて流れが途切れます。一つの節には一つの疑問と、その答えに必要な手順をまとめます。手順の前に理由を長く置くより、必要な前提を短く示し、まず試した結果から説明を深める形も有効です。このプレビューは文章の正しさを採点するものではないため、見出しだけを読んで作業の流れが分かるかは人が確認します。
入力するものと、返ってくるものを分ける
## Input
```json
{"name":"demo","enabled":true}
```
## Expected output
```text
Validation succeeded.
```三つのバッククォートで囲むと、JSONの波括弧や改行をコードとしてまとめて見せられます。ここで表示したValidation succeeded.は文書のサンプル文字列であり、このプレビューがJSONを検証した結果ではありません。入力と出力を同じブロックへ混ぜると、読者が結果の行までコピーしてしまうことがあります。どこをコピーし、何を見れば成功なのかを別々に示します。
コードの手前には、どの画面やディレクトリで使うか、置き換える値は何かを書きます。実行しなくても安全な架空の値を使い、実在する秘密鍵や本番の接続先を例へ混ぜないようにします。プレビューにコードが表示されたことは、実行が成功する証明ではありません。READMEに載せる操作は、別途そのプロジェクトの安全な検証環境で確かめます。
設定の比較は表に、操作の順番は番号へ
| Option | Example | Meaning |
| --- | --- | --- |
| mode | preview | Inspect without applying |
| limit | 10 | Maximum displayed rows |同じ観点で複数の設定を見比べるなら、表が向いています。項目名、例、意味がそろうので、説明が欠けた行にも気付きやすくなります。一方、まず入力し、次に実行し、結果を見るという順番は番号付きリストの方が読みやすくなります。表の一つのセルへ長い手順を詰め込むと、スマートフォンで何度も横へスクロールする文書になりやすいため、用途を分けます。
ここでのmodeやlimitはREADMEの構成を試すための架空の設定です。実際のツールが持つオプションとしてコピーするものではありません。自分の文書へ置き換えるときは、存在する設定、既定値、変更したときの影響を確認します。例の値と初期値も分けて書きます。『10』が一例なのか、利用者が変更しないときの値なのかが分からない文書は、設定ミスの原因になります。
原文の改行が、段落の区切りとは限らない
First line
Second line
Another paragraphこの例では、最初の二行は一つの段落として扱われ、空行の後に別の段落が続きます。原文をエディターの幅で折り返したことと、文章の意味を分けたことは別です。見た目だけで改行を増やすより、一つの段落に一つの話題を置いて、空行で区切ります。プレビューと原文を行き来しながら、どの空行が構造を作っているかを確認してください。
箇条書きのインデントやコードの囲みが閉じていないと、後ろの見出しまで別の要素へ取り込まれることがあります。文書の後半が全部コードに見えるなら、最後の行ではなくコードブロックを開いた位置まで戻ります。崩れた部分を丸ごと書き直す前に、その前後の空行、字下げ、囲み記号だけを小さく変えて試すと、原因が分かりやすくなります。
画像やHTMLが出ないのは、この画面の制限もある
このプレビューは入力内の外部画像を取得せず、埋め込みHTMLもそのまま実行しません。画像が見えないからといって、画像URLが間違っていると断定はできません。リンクもプレビュー内では移動用リンクとして有効化しないため、公開先でのリンク切れ確認とは別です。HTML出力に安全なリンクが含まれる場合でも、この画面で外部サイトを自動的に開くことはありません。
GitHubなどの掲載先では、Markdownの拡張や目次アンカーの生成、画像の扱い、CSSが異なります。ここで構造が読みやすいことを確認した後、最終的な掲載先でも表示を確認します。特定サイトと完全に同じ見た目になることや、相対リンクの参照先が存在することまで、このプレビューだけでは保証できません。確認したことと未確認のことを分けて引き継ぎます。
最後に、初めて読む人になったつもりで『何を用意するか』『何を入力するか』『どの結果ならよいか』『失敗したらどこを見るか』の四点を探します。答えがあちこちへ散っているなら、その一作業だけでも同じ節へ集めます。文章を長くするより、読者が迷う分岐へ短い説明を足す方が役立つことがあります。プレビューは、その並べ替えをすぐに確かめる場所として使えます。