私たちが何かを表現したいとき、自分の知識レベルに制約されます。知識レベルが低いと問題が生じます —— 表現が正確でなく、言葉が不明瞭であるために表現が間違ってしまうことがあります。多くの人はこの手段を使って間違いを回避します。知識レベルが高いことも問題を引き起こします —— 専門用語が多すぎて素人には理解できず、関連する知識が読者の頭の中にない場合、一般の人々が表現を理解するのが難しくなります。
すべての表現にはその受け手がいます。たとえ簡単な文字であっても、受け手が文字を読み書きでき、基礎的な読解力を持っている必要があります；幼い子供は絵本の表現しか受け入れられません。私たちが書く対象は誰なのでしょうか？技術的な文章は著者よりも高いレベルの人に向けられているのでしょうか？
知乎#
今日、知乎を見ていて、ある質問を見つけました 子供に問題を説明するのがなぜイライラするのか？ - 知乎。
あなたは話すときにハイパーリンクを使うのが好きで、心の中にライブラリがあり、情報はそのライブラリから呼び出されますが、子供にはそのライブラリがありません。あなたが送ったたくさんのハイパーリンクはすべて呼び出しに失敗し、あなたが何を言っても子供が聞いているのは 404 not found だけです。
文字や言語自体が一種のハイパーリンクであり、少なくとも読者が単語の意味を理解できる必要があります。たとえば、== ハイパーリンク == はあまり一般的ではない単語です。しかし、ここで == ハイパーリンク == の詳細な説明を長々と挿入することはできません。したがって、この記事の受け手は最低限のインターネットサーフィンの経験を持っている必要があり、私たちが一般的だと考える単語は詳細に説明する必要はありません。
記事を半分読んで理解できない、または半分読んで冗長で意味がないと感じることを避けるために、執筆前に記事の受け手がどのような知識を持っているかを評価することは必要です。
私の執筆#
今振り返ると、私の技術ブログはしばしば読者が特定の技術分野の初心者であることを前提としています。ほとんどのブログ記事は手取り足取りのチュートリアルで、一歩一歩クリックすれば常に期待した現象が見られます。方法論の支援がないとき、私は無意識のうちに読者のレベルの問題に注意を払っていました。誇り (‾◡◝)
しかし、少し深い内容のブログもあり、読者には1レベルの知識が必要であり、読者が持っていない前提知識が大量に必要ですが、関連する説明がないため、読者はあちこちで混乱した資料を探し回ることになります。
傲慢と怠惰#
書籍の文字はページ数に制約されるため、通常、全体の本は一つの問題に重点を置いて解決することが多く、前提技術は一筆で済まされます。
私は良い記事はワンストップのソリューションであるべきだと考えています。この問題が2レベルであるなら、未入門から心転手の読者は一つの記事で問題を解決できるべきです。
ソフトウェア形式の提示のおかげで、一つの記事は全体のプロセスを集中して説明できます。その中の前提知識や詳細は、特定の段落にハイパーリンク形式で挿入できます。
このような良い記事を書くのは時間と労力がかかり、あまり利益もありませんので、私は本当に厳密に自分に要求することはできません。
しかし、私はこのような最終的な基準には問題がないと考えています。そうしないことは、コードを書くときにコメントを書かないのと同じです。コードを読む人が障害なく簡単に理解できるなら、読者のレベルは著者よりもはるかに高いでしょう。
技術的な執筆に関して、私は「詩のように」という評価が良いとは思いません。詩は簡潔で力強い文化的ハイパーリンクであり、詩の解釈は千差万別で、詩の含蓄は豊かで複雑です。しかし、技術に関しては、私の要求はできるだけ正確な記述であり、無数の正確な部品を通じて、正確な技術システムを組み立てることができるべきであり、できるだけ論争や副作用がないようにしてほしいです。
笨執筆#
自分を愚かな著者だと思い、容赦なく自分を絞り出します。
読者を愚かな読者だと思い、猿でも理解できるシェイクスピアを書く。
この記事は Mix Space によって xLog に同期更新されました
元のリンクは https://www.yono233.cn/posts/white/25_4_3_BungleW