Zenn
Open13

ドキュメントの書き方 ベストプラクティス

Markdown
#
document
𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖

リストの説明は先に記載する

Why: そのリストが何か、を先に説明したほうが理解しやすいため。

<!-- Good -->

作業手順は以下のとおりです。

1. XXX
2. YYY

<!-- Bad -->

1. XXX
2. YYY

作業は上記の手順で実施してください。
𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖

コマンドラインに $ を付けない

Why: コピペで実行できなくなるため。

<!-- Good -->

```shell
# 依存関係のインストール
yarn install
\```

<!-- Bad -->

```shell
依存関係のインストール
$ yarn install
\```
𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖

リストには説明を付ける

Why: 読み飛ばしてリストにたどり着いた場合に、そのリストが何なのかを把握できるようにするため。

𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖

順序付きリストは 1. に統一する

Why: 並び替えや追加・削除時にナンバリングが狂わないようにするため。

<!-- Good -->

1. XXX
1. YYY
1. ZZZ

<!-- Bad -->

1. XXX
2. YYY
3. ZZZ
𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖

固有名詞は正式名称や共通の表現に統一する

Why: 統一されていないとその表記が何をさすかの精査が発生するため。

流し読みをしているとき、その表記の形で認識しているような気がする。
可能な限り表現を統一してあげたほうが読み手の負荷を下げられる。

○ GitHub
× Github, github Git Hub

○ Stylelint
× stylelint, StyleLint, style lint

また、表記ブレが発生しやすい固有名詞については、ドキュメント上の表記を統一すること。

Google Chrome, chrome, Chrome, Chrome ブラウザ ...
JavaScript, JS ...
Pull Request, PullRequest, PR, プルリク ...
𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖

シェルスクリプトはコピペで実行可能にする

Why: コピーして実行できたほうがトラブルが抑止できるため。

良い例

シーケンスごとにコードブロックを分解するとより親切。

yarn start # ←実行を開始します

yarn dev
# 8080 番ポートでサーバーが起動する

良くない例

yarn start ←実行を開始します

yarn dev
8080番ポートでサーバーが起動する
𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖

見出しレベルは適切に

Why: なにがどこに記載されているかを目次から参照できる必要があるため。

ブログ記事と違って、その時必要なトピック以外は読み飛ばされる前提で見出しを付けること。
そのために見出しのレベルや付け方には注意を払う。

ページを書いたら目次だけ見て伝えたいことが伝わるかを確かめる。

𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖

アラートブロックを利用する

Why: 特に重要な事象が伝わりやすくなるため。

GitHub における Alerts や Docsify の flexible-alerts を使って、目立たせたいことをより目立たせる。

アラートがあることで、読み手は本文の前提をスムーズにインプットできるようになる。

アラートに書くべき事柄

  • 重要である（どのように重要かについて）
  • 廃止済みである
  • 特定の状態でのみ必要なことである
  • より詳細に記載しているページ・章へのリンク
𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖

接続詞を可能な限り排除する

Why: 文は短いほうが素早く解釈しやすいため。

流し読むときに文は短ければ短いほど良い。文は1文で1つの意味が持たせられているほうが読み手に読むべき部分を選択させやすくなる。
また、1行＝1文とすることでさらに読み手にとって選択しやすい文章になる

接続詞は以下のように処理すると良い

  • 文として分けて、 そのため、 などの独立した接続詞を付ける
  • 接続詞＝改行、句読点＝段落で分ける
𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖𝕤𝕚𝕞𝕠𝕔𝕙𝕖𝕖

手順を説明するときは最初は・次はなどを含める

Why: 段落のうち、ステップの区切りが認識しやすいため。

良い例

はじめに、〜します。

〜〜〜〜

次に、〜します。

〜〜〜〜〜〜

最後に、〜します。

〜〜〜〜〜

以上で〜は完了です。