Google Markdown Style Guide を読んでみる

AI の普及もあり，Markdown でドキュメントを書く機会が増えています．
一方で，Markdown は自由度が高く，書き手によって記法が異なりがちです．
本記事では，Google Markdown Style Guide を読み，
その要点を一部割愛してまとめます．

Google Markdown Style Guide が目指すもの

Google Markdown Style Guide では，次の 3 つのバランスを重視しています．

ソース（Markdown）の読みやすさ・移植性
Markdown ドキュメントの保守性
記法がシンプルで覚えやすいこと

単に「見た目がきれいな Markdown」を目指すのではなく，
長期間・複数人で運用しやすい Markdown を書くことを目的としている点が
特徴です．

ドキュメントの運用

古くなったドキュメントが大量にある状態よりも，少数でも最新かつ正確な
ドキュメントを維持することを推奨しています．

必要なドキュメントのみを残す
不要なものはこまめに削除する

Better is better than best

「完璧なドキュメント」を一度で作るよりも，小さな改善を素早く積み重ねることを
重視します．

Better/Best Rule（「完璧」よりも「以前より良い」を目指す）
一度で完璧なドキュメントを求めない
小さな改善を繰り返す
レビューで問題を指摘する場合は，可能であれば具体的な改善案も示す

大文字・小文字の表記

製品名・ツール名・コマンド名は公式の表記を使用する
大文字・小文字を勝手に変更しない

ドキュメント構成

次のような構成を推奨しています．

タイトル（H1）
導入（1〜3 文）
目次
本文（H2 から開始）
関連リンク（See also）

# ドキュメントタイトル

簡単な導入

[TOC]

## トピック

内容

## See also

* 関連リンク

ドキュメントタイトル
- 最初の見出しは H1（#）で書く
- ファイル名と近いタイトルが望ましい
簡単な導入
- 1〜3 文程度でドキュメントの概要を説明する
- 完全な初心者が読むことを想定して書く
TOC
- 短いドキュメントを除き，目次を設置する
- [TOC] は Gitiles で目次を生成するための記法である
トピック
- H2（##）から始める
See also
- 関連リンクをまとめる
- ドキュメントの最後に置く

1 行の文字数

コードと同様に，1 行の文字数は 80 文字以内にすることを推奨しています．

コード用ツールとの親和性
エンジニアのコーディング習慣との統一
コードレビュー文化の恩恵を受けやすくするため

ただし，次の場合は 80 文字を超えても問題ありません．

リンク
表
見出し
コードブロック

行末の空白

行末の空白（trailing whitespace）は使用しないことを推奨しています．

改行が必要な場合は，行末にバックスラッシュ（\）を使用する
バックスラッシュによる改行も必要最低限にする
<br> や行末スペース 2 つ（）による改行は推奨しない

見出しの書き方

ATX 形式の見出しを使用する（# を使用する）
内容が分かる具体的な見出しをつける
アンカーリンクを考慮し，見出しは一意にする
# の後ろにスペースを入れ，見出しの前後に空行を入れる
H1 は 1 つだけ使用する
タイトルや見出しの大文字・小文字の表記は，
Google Developer Documentation Style Guide
に従う

リストの書き方

長い番号付きリストは lazy numbering を使用する
- 番号を 1. 2. ... と書かず，すべて 1. にする

ネストしたリストでは，本文の開始位置が揃うように，4 スペースを基準としてインデントする

1.  あいうえお
    折り返し
2.  かきくけこ

*   item
    1.  subitem
        折り返し
    2.  subitem
*   item2

ネストや折り返しのない短いリストは，シンプルな記法でもよい
```
* item
* item2

1. item
2. item2
```

コードの書き方

短いコード，フィールド名，コマンド，ファイル名はインラインコードとしてバッククォート（`）で囲む
Markdown や自動リンクとして解釈されたくない文字列も，バッククォートで囲む
複数行のコードは，バッククォート 3 つ（```）で囲んだフェンス付きコードブロックとして記述する
コードブロックでは，言語の指定を推奨する
```
```python
print("Hello, World!")
```
```
4 スペースインデントによるコードブロックではなく，フェンス付きコードブロックを使用する
長いコマンドは，行末の \ で改行する
リスト内のコードブロックは，リスト構造が崩れないようにインデントする
```
* item

  ```python
  print("Hello, World!")
  ```
* item2
```

リンクの書き方

リンクは可能な限り短くする
同一サイト内のページには，完全な URL ではなく，サイトのルートを基準としたパスを使用する
相対パスは，同一ディレクトリ内のファイルに対してのみ使用する
- ../ を使って別のディレクトリを参照することは避ける
  （ドキュメントの移動時にリンク切れになる可能性があるため）
here，link，URL そのものなど，リンク先の内容が分からないリンクテキストは避ける

長い URL には参照リンクを使用する

[Markdown スタイルガイド][style]を参照してください．

[style]: https://example.com/very/long/path/to/markdown-style-guide

表内の長いリンクや，同じリンク先を繰り返し使用する場合にも，参照リンクを使用する

| Site     | Description    |
| -------- | -------------- |
| [site 1] | Example site 1 |
| [site 2] | Example site 2 |

[site 1]: https://example.com/very/long/path/site1
[site 2]: https://example.com/very/long/path/site2

参照リンクの定義は，最初に使用したセクションの末尾に置く
- 複数のセクションで使用する参照リンクは，
  ドキュメントの末尾に置く

画像の使い方

画像は必要最低限にし，シンプルなスクリーンショットを使用する
文章で説明するより，画像を見せた方が分かりやすい場合に使用する
- UI の操作手順など
画像には，内容を説明する適切な代替テキストを設定する

表の使い方

素早く比較・確認したい表形式のデータに使用する
リストで簡単に表現できる場合は，表を使用しない
次のような表は避ける
- 行ごとの差が少なく，同じ内容や空欄が多い
- 行数と列数のバランスが悪い
- セル内に長い文章が含まれる
次のような場合は表が適している
- 縦横に均等にデータが分布している
- 多数の項目を，複数の属性で比較する
表内の長いリンクには参照リンクを使用する

HTML より Markdown

可能な限り，標準的な Markdown 記法を使用する
HTML による回避的な記述は避ける
Markdown で実現できない場合は，その表現が本当に必要かを見直す
HTML を混在させると，可読性や移植性が低下する

まとめ

Google Markdown Style Guide は，レンダリング後の見た目だけでなく，
Markdown ソースの読みやすさや保守性も重視しています．

すべてのルールを機械的に適用するのではなく，
複数人で長期間運用するドキュメントを読みやすく保つための考え方として
取り入れることが重要なのかもしれません．
（個人的にはちょっと使いづらい部分も...）

関連リンク