質の高い技術文書を書く方法 - As a Futurist...

大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体

[riywo]

書いてみた

[tettekete37564]

文書の最も簡潔なオーバービューというのは目次になる。そして目次は箇条書きのネストになる。情報の構成概要を表したり、その要素を列挙するならば箇条書きを忌避する理由はない。特に条件や要件の列挙など

[non_117]

箇条書きをネストしたやつ人に読ませるものではないよね

[unique120]

この文章を読んでも、よく意味がわからないのですが。

[baca-aho-doji]

めちゃめちゃいい文章。仕事の質を上げるのに必要なことがたくさん書いてある。これを自分がやれてるかっていうとやれてないなと思うことが多いので改めて見つめ直したい。

[KullbackLeibler]

長い

[tossy_yukky]

言ってることは正しいと思うけど、ネット上にある文章としては体裁が本に寄りすぎてる感。

[nWY2RhxQPXKQloX3z]

異様に一文が長かったり、「これは」「その」「それ」「こうした」などの指示語が多い印象を受ける。

[table]

読み手の質に合わせる事が一番大事

[jmako]

長すぎて最後まで読む気にならなかったw 最初の三行で重要なことのみ書いとけよ！！

[Casseroles]

“が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。”

[lycolia]

人に説明しやすい質の高い文章の書き方について

[takatama]

Amazon流。結論から書こうとすれば、結果的に考え抜いた文書になる。周囲に優れた文書があふれていると、自分のレベルも上げやすい

[Kazumi007]

ドキュメントは難しいよね

[tjmschk]

社内の文章をつくるためにお勧めされて読んだけど、すでに猛スピードで書き上げてからロクに見直してないアドカレをもう書き直したくなってきている。

[ymgn]

このあたりちゃんと守れてたらいいドキュメントとかアジェンダとか作れそうだ

[cupeytan]

”この文書を初めから最後まで読んだ人は一体どんな情報を得られるのか？ということを文書を書く前に決めるのだ。“

[sugoi_wada]

“文書から得られるアウトプットが明確で、読み手のレベルによらず一定に伝わること”

[king-masashi]

文書を書く時の参考にさせていただきます。

[mura-_-mi]

大事

[yunohito]

/72438b38f545fac8ca9133502d178901/bef64/riywo.webp 100w, /static/72438b38f545fac8ca9133502d178901/9e195/riywo.webp 200w, /static/72438b38f545fac8ca9133502d178901/5ba9d/riywo.webp 300w, /static/72438b38f545fac8ca9133502d178901/23b25/riywo.webp 367w" sizes="(max-width: 200px) 100vw, 200px" /><source s

[kiririmode]

working backward

[gadgeterkun]

何度も読み返したいブログ

[Sixeight]

読み手を意識してない箇条書きをしがち。。。文章苦手なので練習しよう。

[tookikimie]

「決断を下したいのであれば、1 つの選択肢を第一候補として、何も異論がなければそのまま、そうでなければ理由を添えて別の選択肢へ、という進行にした方が合意を取りやすい。」

[braitom]

すごくよかった。定期的に読み直したい。"文書から得られるアウトプットが明確で、読み手のレベルによらず一定に伝わること"

[d4-1977]

「文書を作る過程に於いて一貫して「アウトプットがなんなのか？」を問い続けることが最も大切なこと」🙇🏻‍♂️ワカル。ムズカシイ

[mohri]

「箇条書きは短文で済むので文書を速く仕上げることができる一方で、行間を読むことを読み手に強制する」

[kazoo_oo]

とてもよい。

[Tomosugi]

この場合の技術文書はtechnical documentの訳だと思うが、実務文書のほうがしっくりくる

[ktmtto]

研究概要を人（専門/専門外理系/専門外文系）に説明するための文書を書くときに参考にする

[zigzag1900]

いくらその技術があっても、そういう文化でないとそっちに淘汰されてしまう。

[wyukawa]

わかる。が、自分が出来ているかというと。。。

[iwasiman]

長いけどなんか凄く良いガイドがキタ！人に読ませる文書を心掛けたいものです。

[koji28]

「文書の目的を最初に完結に書くと…文書の期待値を大まかにコントロールできる」読み手の期待値をコントロールする…かぁ(´・ω・`)

[iekusup]

ほー。

[yuki_2021]

最初に結論を書くということ。論文とかでも使われる考え方だね。

[iwanofsky]

ハウツーを読んだからどうかではない。 読んで実践し自ら振り返るか、または他者から指摘を受け、次実践あるのみ。 書いた数が多いと高くなるわけでもない。 どう変えたことによって、どのような反響や効果が出たか？

[halfrack]

むっちゃいい内容

[showii]

これでも長すぎて読んでる人少ないのでは？