記事の中で特に目を引く2つの引用があります。まず、Xのスクリーンショットからの引用: 「書くプロセスには、あなたのアイデアを10倍良くする何かがある」。次に、冒頭近くからの引用: 「説得すべき最も重要な人は著者だ」。デザイン文書はとても重要で、業界での数年を経ても、いわゆる「プロダクトマネージャー」たちがこのアイデアに反対するのを見ると驚きます。レスリー・ランポートが言ったように、「書くことは、私たちの考えがどれだけ雑であるかを教えてくれる自然の方法です」。技術的な文章の質を向上させたい人は、「アマゾニアンのように書く」を見てみてください: https://medium.com/@apappascs/write-like-an-amazonian-14-tip...

自分だけが読むことになるかもしれないデザイン文書を書くこともあります。こういうことを書き留めるのは本当に力強いです。参考になる例文書があれば、他の人の最終的な構造と自分のを比べてみたいです。

アマゾンで7.5年働いていて、サイドプロジェクトでもPRFAQを書いて、ステークホルダーと共有してフィードバックをもらっています。アマゾンではPMTですが、別の人生では多くのプロジェクトでコーディングをして、インフラやアーキテクチャを開発しています。できるだけ多くのことを書くのを楽しんでいます。とはいえ、顧客のニーズを最優先に考えよう！

デザインレビューをする立場として、すべてのデザイン著者はこの概念を内面化すべきだと思います。> しかし、良い文書は問題とメンタルモデルを示し、数週間の思考を経て生まれた解決策が文書を読む頃には明確になるようにします。私のお気に入りの引用はこれです: 「もっと時間があれば、短い手紙を書いただろう」。デザイン文書は複雑なことをシンプルにするべきです。エンジニアが経験した知的な苦労や失敗の記録のゴミ箱になってはいけません。それを記録する価値はあるかもしれませんが、それは別の文書、もしくは少なくとも付録にすべきです。前に進む道はシンプルで理解しやすく保ちましょう。

こういう文書が大好きで、書く文化全般も好きです。でも、これが裏目に出ることも見たことがあります。このアプローチは、読者があなたが出した結論に至った理由を理解したいと思っている文書には特に良いと思います。文書が説得力のある議論のようなものです。これは貴重な文書だと思います（私が書くのも読むのも好きなスタイルです）が、常にそうとは限りません。しばしば、結論、つまり「終わり」から始めて、読者を方向付けるのが良いと思います。また、あなたの判断を信頼している読者に対して、スピード感を持たせるためにも。読者が論理の流れに沿ってついていく準備ができていない場合も多く、彼らはオチを知りたいのです。一度それを知れば、続きが気になるかもしれません。

私の経験では、組織や明確さが、ドキュメント作成を改善しようとするソフトウェアエンジニアにとって最大の障害です。著者のスパゲッティコードの比喩は、文書内でのアイデアの整理の重要性を示していて、私も同じ概念を伝えるのに苦労していたので、今後これを使おうと思います。以前は、読者を思考プロセスを通じて「運ぶ」ことについて話しましたが、この投稿はその概念をより親しみやすい形で説明しています。昨年、似たような投稿を書いたことがあり[0]、異なる会社の人との類似点（簡潔さ、練習の重要性）や違いを見るのは興味深かったです。「短い段落」については同意できないかもしれません。それは情報密度の高い文章の自然な結果かもしれませんが、アイデアが洗練されていなければ、行の区切りだけではあまり役に立ちません。「編集」セクションは、その根本的なアイデアにもっと直接触れていると思います。[0]https://ryanmadden.net/things-i-learned-at-google-design-doc...

テクニカルライティングのクラスを受けたおかげで、文書を要約する能力が大幅に向上したよ。このコースでは「赤ペンで切る」アプローチ（書いて、消して、書き直す）を強調していて、できるだけ少ない言葉で概念やアイデアを明確に伝えることに焦点を当ててた。これにはいくつかの層があって、練習するほど簡単になるんだ。チームともこの知識を共有しようとしてるけど、定期的なトレーニングが必要なスキルだってことを忘れちゃいけないね。

明瞭さと編集に関する良いアドバイスだね。ただ一つの欠点は、文書が承認された後はどうなるかってこと。メンテナンスがないと「デザイン考古学」になっちゃう。数年前、アンドリュー・ハーメル＝ローが、軽量なアーキテクチャ決定記録（ADR）を使った会話的なアーキテクチャのスケーリングについて面白いアプローチを書いてたんだ。ADRsはコードの横にあって（adr/001-use-postgres.md）、コンテキスト、決定、ステータスを短いフォーマットで記録するから、PRのたびに見直せるし、現実が変わったときには簡単に上書きできる。元の理由が数ヶ月後も検索できる状態になるんだ。興味がある人のために、ハーメル＝ローの投稿のリンクを貼っておくね: https://martinfowler.com/articles/scaling-architecture-conve...

アマゾンの会議は、プレゼンターが文書のコピーを配るところから始まる... 会議はみんなが黙って座って、文書を読み、赤ペンで余白にメモや質問を追加するところから始まる。アマゾンで働いたことはないけど、これをよく聞くし、いつも変な慣習だなと思う。さらに奇妙なのは、どうやらこれがうまくいくらしく、話す人たちはみんなこれを好きみたい。みんなが一緒に文書を読んでいる間に貴重な会議の時間を無駄にしてるよ。会議の前に同じことをやれば、もっと短い会議になるのに。同期でやるってことは、みんなが一番遅い読者が準備できるまで待たなきゃいけないか、全員が時間内に終わらないってことだし。「一番遅い読者」ってのは、単に読みの速さだけじゃないと思う。おそらく、文書のコンテキストをもっと理解している人は、早く理解できるんだろうね。グーグルのデザインレビューでは、ほとんどの参加者が準備不足で、チームメイトが文書を議論している間に初めて文書を読んでいるのが明らかだった。おそらく、グーグルには強い文書文化がなくて、リーダーやマネージャーは人々が準備不足で来るのを静かに許容していたんだろう（時には、彼ら自身も準備不足だったり）。実際に見たことはないけど、レビュー会議の前に文書をレビューすることで、両方の良いところを取り入れるのは難しくないと思う。文書を事前に読むことが強い文化的規範になれば、会議はただの議論の場になるはずだし、ただ読むための場や、読んだふりをするための場にはならないはず。

効果的なプロセスの一つ: ステップ1. 文書に思いつくことを全部書き出す（もっと早く考えをまとめるために音声入力を使うのも考えてみて）。ステップ2. LLMに構造と進行を与えてもらう。読みやすさのために考えを整理しているから、たぶん捨てたくなるだろうね。この段階ではまだ考えを洗練しているところだから。ステップ3. LLMの出力を出発点として使うか、最初からアウトラインを書く。そこから初稿を作り上げる。ステップ4. 簡素化する: 言葉を削ったり、大きな言葉を小さな言葉に置き換えたり。ステップ5. ステップ4を繰り返す。LLMは言葉の洪水から構造への橋渡しをしてくれる。LLMから得たものは捨てる覚悟を持つべきだね。少なくとも30%は常にカットできる。意図を失わずにどれだけ削れるかは驚くべきことだよ。