『読み手に伝わる文章 - テクニカルライティング』を読んだ
技術書典で購入した本。
読む目的、目標
今すぐ使えるドキュメント作成に生きる部分を知りたい
久々に技術記事を書いたが、自分でもいまいち納得のできない出来だったので、改めて分かりやすいドキュメントとは？を理解したい
書くだけではなく、ドキュメントの整理方法もあれば知りたい
同僚のスライドに影響を受けて、試しにこの本から「目的、目標」を掲げてみた。
https://speakerdeck.com/mrtry/ji-shu-shu-falsedu-mifang-ru-men
読書をするときにあれもこれも重要に思えてメモを取ってしまい、読み終えるのに時間がかかったり、社内ので読書会でも「読むこと」に重点を置きすぎて内容に疑問を抱いたりといった一歩進んだ理解ができないという悩みがあった。
その困った部分の解消になりそうなので、今回から始めてみた。
テクニカルライティングとは
テクニカルライティングとは、「手段」としての実用文を書くときに伝えたかったことを分かりやすく書くための技術。家電の取扱説明書、技術ドキュメントやAPIリファレンスなど。
引用という形を取っているが、この記事全体的に記述そのままではなく要約したり省略したり、自分の理解度に合わせて書き下している。
本来の内容を読みたい場合は、ぜひ本を読んでほしい。
分かりやすいドキュメントとは？を理解したい
最初に「想定する読者層」「マッチしない読者層」と「ゴール」を書いておくことで、読者のミスマッチを防ぐことができるし、著者自身が方向性を見失いかけた時の拠り所になる
最近は冒頭にこのような「想定する読者層」や「ゴール」を掲げている記事を読むことも多くなり納得しやすかったが、普段記事をあまり書いてこなかったこともあり、著者自身へのメリットは目から鱗だった。
書いてある情報を必要としない層を早めに古い落とす。必要のない人に無駄に文章を読ませない。
読んだ人が「私は何をどうすればいいのか」という答えを見つけて、やるべき作業に早く進めた方がいい。
この考え方はあまりなかったけど、改めて考えてみると記事や本の目次で何について書いてあるかをさっと目を通すことは普段からしていることに気付かされた。
その他にも良いなと思ったものを抜粋。
今すぐ使えそうなドキュメント作成に生きる部分
書き始めの遅さをAIにサポートしてもらって初案を作り、手直しをしていく。書く速度が速いと見直しやレビューに時間がかけられるので、最終的に出来上がる文章の品質も上がる。
技術書典会場で試し読みしたとき、目次でこれを見て購入を決意した。
AIの具体的な使い方について書いてあるわけではないが、確かに記事を書くときに1番のハードルは書き出しの遅さ。それをカバーするためにAIを使うのはとても有用そう。
いきなり壮大なドキュメントを書くのではなく、一文、ひと段落、一記事、複数の記事で構成されたドキュメントのように段階的に難易度を上げていく。
つい最近、 Gatsby の記事を何回かに渡って書こうとして失敗したなと思っていたのがまさにこれ。小さくやり直そうと思う。
それ以外にも、すぐにでも取り入れたいなと感じたものたち。
細かいテクニックを学ぶより先に、まずはなんでもいいからいっぱい読む。分かりやすい表現、分かりにくい表現というパーツをたくさん読んで集める。
書き方に悩んだときはたくさんのパターンを並べて書いて、その中から最善案を見つけるという方法がおすすめ。ヒストリーと差分が見えるように直前の案をコピーペーストしながら全部の案を並べて書いて、一番よい一文を見つける。
一番大事なこと。
何より大事なのは、完成度を上げることよりもとにかく完成させて世に出すこと。書き始めてようやく知識が不足していることに気付く。締め切りを設定して完成を目指すのも有効。
ドキュメントの整理方法もあれば知りたい
社内のドキュメントの多くが Confluence で書かれているが、作業ディレクトリ内に雑然とまとまっていて探しづらいという状態に陥っている。この辺りの具体的な整理方法のアイディアが欲しかったが、あまり書かれてはいなかった。
「本当に必要なもの」と「古い情報だが取っておきたいもの」が同じ場所に雑然と置かれていることのないようにする
ページのタイトルだけを見て分かるようにする。他のドキュメントから当該ページへのリンクを貼るときに、リンクテキストがそれだけで内容が分かるものになっていた方がよい。
書き方にはなるが、一つのページにいくつもの手順が並列に並んでいたり、ページタイトルに悩むことが多々あったので解決方法の手段として取り入れていきたい。
良いレビューの仕方とされ方
読書の目標にはなかったが、レビューのコツが普段のプログラミングの仕事にも活用できそうで良かった。
「具体的にどう直すか」が読み取れない指摘は、「どう直したらいいか分からない」と延々と考え込んでしまって時間を無為に使うことになりがち。レビュアーにとって嬉しいことではない。具体的な修正提案や期待値を明確に提示する。ない場合は「こういうふうに自分は分かりにくいと感じたけど、具体的な代替案は思いつかなかった」と気持ちだけ伝えても良い。
レビューを受ける時に、相手のレビューコメントが分かりづらいと感じることがあった。相手に「こうして欲しい」というのをどこまで伝えていいのか悩むことがあったので、その時の判断軸にしてみようと思った。