Booklog - ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング

前回が軽かったので今回は積読消化回。積み過ぎて日があたってたところのオレンジが褪せてる。 わたしは仕事でサブシステムを作ったら文書や障害対応の手引なんかを書くのは結構好きだ。 それに対し称賛されることもあるけど、逆にしょーもないことすんなと批判されることもある。 書いてもコイツラ読まへんなーという状況も常にあるので、なんかきっかけを掴めたらいいな。 「ドキュメントは機能の 1 つ」、いいなあ。はじめに、は入門 Kubernetes の人。 この本はツールになるべく触れてないらしく、良い。ツールで解決できたら誰も困ってないもんな。

2024-09-15, read count: 1, page: 1 ~ 28, pages read: 28

chapter 1 終わり。 この本でも届けたい相手のペルソナを作る。「遠くへ行きたければ、みんなで行け」でも「インディゲームサバイバルガイド」でもそんな感じだった。 仕事ではガチでやるのは当然として趣味レベルでサクッと始めるには重いな。呼吸をするようにペルソナを作れるようになれってことなのか。 社内向けにはあえて知識の呪いにかかったまま文書を書くこともあるけど、どうなんやろね。ペルソナにそぐうならいいのかな。

2024-09-16, read count: 1, page: 29 ~ 46, pages read: 18

chapter 2 終わり。 ドキュメントのタイプとパターンというのは意識して考えたことなかったので学びになった。 届けたい先に合わせて提供するパターンが変わる。ここは何度か噛みしめるように読もう。

2024-09-17, read count: 1, page: 47 ~ 68, pages read: 22

chapter 3 ドラフト。 ドキュメントの構成要素を使い分け、流し読み上等で簡潔に、重要なことははじめに書く。 完璧を目指さず満たすべき要素を網羅してるか注意して初版を書き上げたら一歩踏み出せたと。 なかなか普段ここまで考えて書いてないなって気がするわ。

2024-09-18, read count: 1, page: 69 ~ 92, pages read: 24

chapter 4 編集。 技術的な正しさと必要うな情報の完全性はやってそうやけどその後の構成とか簡潔さの編集は中々訓練してない難しそう。 フィードバックの受け方送り方。 plussing は覚えとこう。 ストーリーにもあるけどコードレビューと同じなので HRT を意識したいところ。

2024-09-19, read count: 1, page: 93 ~ 106, pages read: 14

chapter 5 サンプルコード。 目的が明確で簡潔で正確で拡張可能であること。テストされてて自動生成でサンドボックスがあって、みたいな話。 そーいや前 .NET のドキュメントの repo 見たときもスクリプトは分かれてたなー、そういうあれか。つながった。

2024-09-20, read count: 1, page: 107 ~ 124, pages read: 18

chapter 6 画像や動画といったビジュアルコンテンツ。 視覚的により読者に理解しやすいが、アクセシビリティの配慮と陳腐化の速さに難しさがある。 インフラ構成図とか書くといつも線が絡まるので、そもそも図を書くの難しいねんよなと思っている。

2024-09-21, read count: 1, page: 125 ~ 144, pages read: 20

chapter 7 公開。 結構重厚なフローやけど会社のサービスのドキュメントともなればそういう感じかも。 CD してないと詰むなと思ったが、はじめは toil を実感するためにシンプルに手動でやるとのこと。そうなのか... 自作のツールはリリースノートちゃんとやってないしはじめてみるかー。

2024-09-22, read count: 1, page: 145 ~ 156, pages read: 12

chapter 8 フィードバックの収集とその対応。 課題の完了をユーザに通知するのを推奨してるが、しないとこ結構ありそうな印象。どこぞのクラウドも皆無だったし。 ユーザーコミュニティの設立についてはサラッと触れられてる程度。 People Powered 読んだ感じ思いつきで始めれるもんでもないし、ここで深追いする話ではないからそんなもんか。

2024-09-23, read count: 1, page: 157 ~ 171, pages read: 15

chapter 9 品質測定。前半は知らないことが多く、ほーという感じだった。 Textlint は使ってるけど、 HemingwayEditor も試してみよう。測定するまでもなく機械的に改善できるならあらかじめやっておきたいよな。 なんかプロジェクトの KPI を定めるのと同じような印象を受けた。

2024-09-24, read count: 1, page: 172 ~ 191, pages read: 20

chapter 10 構成。情報アーキテクチャ出てきた。ずっとやらずに来てるなー。 情報アーキテクチャで利用者がコンテンツのメンタルモデルを作り上げるのを支援するらしい。 作って終わりじゃないので保守に本質があると思うしメンタルモデルを検証し続けるって書いてるけど、それは次の章みたい。

2024-09-25, read count: 1, page: 192 ~ 207, pages read: 16

chapter 11 保守と非推奨化。これで本編は終わり。お気持ち表明みたいなのなくあっさり終わったのが本書らしい気もする。 サービスとドキュメントのリリースを同期するのとか、リファレンスの生成、保守作業の自動化らへん。 7 章でもそうだったけど本書は自動化に慎重派で、 toil を見極めてやれよと。 web ドキュメントが標準の原題だと削除って選択肢はなかなかないやろうな。実際よくページが無くなって困るし。ページ残して新しいのに流すか、自動でリダイレクトか...

2024-09-26, read count: 1, page: 208 ~ 221, pages read: 14

付録。ドキュメンタリアンの採用、ドキュメントに取り組み続けるためのリソース等。 htmltest は知らなかったがすぐ使えそうなので試してみる。あとがきにもあるがあとは実践あるのみよな。 仕事と趣味プロでドキュメントライティングを実践していこう。

2024-09-27, read count: 1, page: 222 ~ 242, pages read: 21