【読書メモ】エンジニアのためのドキュメントライティング

エンジニアのためのドキュメントライティング　を読み始めました

https://amzn.asia/d/6pfNamk
ここでのドキュメントは、設計書というよりトラブルシューティング用のチートシートっぽい

あるいは取扱説明書か
ようするに：

ソフトウェアシステムの立ち上げ、トラブルを迅速化するための資料を作るには、の本
※冒頭から「ユーザー」という単語が多用されるが、あくまでドキュメントのユーザーであって、エンドユーザーと同義ではない

社内の開発者かもしれないし、クライアントかもしれないし、エンドユーザーかもしれない

なんにしろターゲットは早期に決めるのが必須
1章の前半は「敵（ユーザー）を知る」的な内容と解釈しました
ユーザーが何を求めているのか（願望的な任意目標ではなく、必須性の高いもの）
共通点は何か（すべてに対応することはできない）
どうやって収集するか（インタビューやアンケート）
ドキュメント作成に重点を置いているため、シナリオプロジェクトが技術的に抽象的になるよう工夫されてる　良い

木目壱心

2日目 意見の整理
意見を集めてもすぐに資料にするのは難しいので、整理が必要
ユーザーペルソナ
対象ユーザーのキャラ設定をまとめたもの。
そのドキュメントを特に必要とする人物像を組み立てる。（支援が必要、学習曲線が急）

ユーザーストーリー
ユーザーが達成したいことをまとめたもの
「誰」が「目的」を達成するために「何」をする？

ユーザージャーニーマップ
ユーザーストーリーを時系列順に整理したもの。
ハードルが高くなる部分に注目する

フリクションログ
目的達成の障害になるありとあらゆる事象をまとめたもの。
障害が多いソフトウェアは、当然使いたくなくなる。
「誰」が、「ある状態」から、何を「目標」に行動するかをまず決める。
目標達成までの間に詰まった部分を記録する。（達成難度も）

手順書を作る（作ってもらう）ことがよくあるので、

フリクションの観点は明示してもらうのがよさそう（ここ対処するのが大変だった　みたいな）

木目壱心

3日目　ドキュメント作成の計画
開発者向けのドキュメントの種類と目的が整理された章です
コードコメント

コードからは読み取れない内容を明記する
README

ソースコードを包括した内容を記述する

コードの更新と連動させること（これがめんどい）
スタートガイド

とりあえず使い始められるようにする資料
コンセプトドキュメント

システムの目的がわかる資料（要求仕様書に近い）
手順書（チュートリアル、ハウツー、リファレンス、用語集、変更履歴）
目的を絞って一覧性を高めた資料
手順の工程は少なく、前提条件は最小限にするのが望ましい
外部ファイルやリンクへの依存が少なく、資料単体で成立する方が良い

木目壱心

4日目　白紙との戦い　ドキュメントを書き上げる手順
書き始め

0. 使い慣れたツールを使う
誰に何を伝えるのかを明確にする
タイトルを決める（ゴールは1つに絞る、動詞で終わること）
アウトラインを作り、書くべき情報をすべて列挙する
下書き

0. アウトラインが完成していること
見出しを決める：簡潔で、重複がなく、一貫性があること
書き始める　以下の要素を注意・活用すること
1段落は5文以内
手順は番号付きリストで表現
列挙はリストで表現
重要な余談はコールアウトで表現
読み手は全部読んでくれないので流し読みできるようにすること！

重要なことは冒頭で言い、長い文章にしない
書き終えるために

0. 行き詰まったら、その原因を考えてみる
完璧を目指さない
無理に自己解決しようとしない
後から埋めることをメモる
書きやすいところから書く
執筆ツールを変える
ほぼコーディングな気がする
（前から思ってたけど）文章は読み手というインタープリタに渡すスクリプト言語みたいなもの
関数に分割したり明確な命名をすることが推奨される
リーダブルドキュメントを書きたい

木目壱心

5日目　レビュー
コードレビューのテクはコードレビュー以外にも使えそうです。
執筆と編集を分ける → 作業者とレビュアーを独立させるのはあたりまえ
レビューで注意すべき観点
技術的に正確か = 設計書と矛盾のある実装になっていないか
完全性を満たしているか = 設計書の内容が反映されているか
構成はわかりやすいか = リーダブルな実装ができているか
明確で簡潔か = 構文エラー的な問題はないか、命名規則は安定しているか

※PEP8的なガチガチの規約が欲しくなる。自然言語向きではないかもだけど

コードレビュープロセスを流用する

※テキストファイルで管理したいな…
レビュアーをうまく使う
どの観点でレビューしてほしいか
どうやってレビューしてほしいか

矛盾したレビュー指摘→読者のためになる方を選ぶ
批判するとき→建設的な意見を盛り込む
LGTM本のエッセンシャル版みたいな章だった。

木目壱心

6日目　サンプルコード

説明はもうたくさんだ、とにかく動かしたい

は読み手（開発者）の自然な欲求なので（身に覚えしかない）、いいサンプルコードをドキュメントに含める
サンプルコードは説明とセット
読み手が改造しやすい例にする
fooとかhogeは使わないこと、新参者には通じない

できるだけ単純に
何をやっているのかがすぐ分かる
完全な処理結果も示す
想定言語は絞る（APIはcurlで）

余計なことはしない
横スクロールが必要なサンプルはダサいからやめろって書いてあった。同意
Swagger/ OpenAPIの、ドキュメント内にテストツールが埋め込まれてるのはホントにいい仕様だと思う。好き。

（ま、受領資料に限って言えばサーバー側が設定されてないから実行できたためしないけど）