最近GitHub Actionsの公式ドキュメントを読んで感動した。
読み手への気遣いに溢れている。
これはまさに私のために書かれた文章だ。そう思わせてくれる。
お手本にしたいと思ったので、まとめてみる
良いと思ったポイント
1. タイトルが明快である
タイトルが短く明快だ。
2. イントロで何が書かれているか端的に記載されている
よく見ると少し色が薄くなっている。
コントラストで情報に強弱を付けて読みやすくしてくれている。
もし仮にタイトルと同じスタイルだったら、平坦な印象を受けていただろう。
3. サイドバーでその記事が、ドキュメント全体で、どこに位置するか示されている。
全体像と現在地が分かる。
何を学んでいるか俯瞰できる。迷子にならない。
4. 記事に目次が用意されている
冒頭部でその記事の構造がわかる。
基本的なことだが、あるとやっぱり便利。
そして、タイトルとイントロの真下にある、
この文章は何を目的として、何が書かれているか一瞬で把握できてしまう
5. ひとつひとつの文章が短く読みやすい
認知的負荷がまったくない。
パラグラフ・ライティングのお手本のようだ
特に一文目に注目してほしい。
ページと図のカラーコントラストも良い
6. 前提知識が必要な概念や用語に、リンクが設定されている。
しかも、ポップアップで概要が表示される仕掛けまである。
嬉しい。気遣いに涙が溢れそうだ。
7. 全体として文章量が抑えられている
スクロールバーが極小になったドキュメントを見る事がある。
ぺちゃんこになったスクロールバーに何度心を折られたことか。
「これなら全部読みきれる、読もう。」
そう感じさせてくれる文量だ。
非常に考えられている。
8. 読み手の行動を予測して、必要な情報が書かれている。
ワークフローを定義するYAMLファイルの説明が非常に秀逸。
左側にコードスペース、右側に解説文。
構造を示しながら、一個一個理解できる作りになっている
しかも、前セクションでサンプルワークフローを表示し、
ハンズオン形式でサンプルワークフローを作成する流れになっている。
指示に従い手を動かしてみると、ワークフローが設定できるが、
その次には、「どういう構造だろう？」と疑問が浮かぶ。
これがフックになって、内容に興味が向く仕掛けだ。
気づいたら、思考誘導されていた。
からの
である
9. 最後に読み手が次に取るべきアクションを示唆してくれている
つぎに読むべきドキュメントを、予めサジェストしてくれている。
本当に何から何まで、至れり尽くせりだ。
感想
この芸術的なドキュメントを書いた方に、盛大な拍手を送りたい。