技術の解説記事を、そのまま動くコード例つきで書く

## 経験のあるエンジニアが、仲間に説明する口調で書く 経験豊富なengineerがホワイトボードを前にpeerと問題を解いているように、技術的に正確で、率直かつ温かく、堅苦しくない口調で書く。読者に完全な予備知識があるとは決めつけず、その知性を尊重する。何が機能し、何が機能しないのか、その理由とともに述べる。 読者を協力者として扱える場合は、「私たち」や「〜してみよう」のような包摂的な表現を使う。素早く要点へ進み、説明の多くを例に担わせ、説教調にならない自信のあるvoiceを維持する。 ## 本当の問題から始め、動くコードを早めに見せる 各sectionの冒頭は、読者の方向を定める1〜3文に留め、その後で本題へ進む。抽象的な期待ではなく、実際のtask、failure、運用負担によってtopicの必要性を示す。 conceptと同時、または紹介した直後にcodeを示す。pseudocodeより、実際に実行できる例を優先し、読者が動作を確認できる状態にしてから重要な仕組みを説明する。genericなsolutionへ曖昧に言及せず、具体的なtool、実際のcommand、代表的なerror messageを使用する。 ## 段落を短くし、まっすぐな言い方の文で書く paragraphはおおむね3〜4文に留める。密度の高い情報は、文章の壁を作らず、bulletまたはcode blockへ移す。関連する考えはsemicolonよりも `and` または `but` でつなぐことを優先し、短い補足にはparenthesesを重ねずdashを使用する。 可能な限りactive voiceを使う。instructionにはimperative moodを、動作の説明にはpresent tenseを使用する。英語では `we'll`、`you're`、`it's`、`don't` のような自然なcontractionを優先し、展開形は意図的に強調する場合だけ使用する。 ## 前に知っておく事や関連する話へ、説明しすぎずにリンクする technical termを正確に使い、自然に導入する。本当に必要なtermでない限り、glossary形式のdefinitionを追加してはならない。topicにprerequisiteがある場合は、その名前を示して関連materialへlinkする。 cross-referenceをbreadcrumbとして使い、現在の説明を前後のtopicへつなぐ。tool、project、人物には名前を挙げてcreditを示し、「ここをclick」のような文言ではなく、内容が分かるinline linkを使用する。articleで扱える範囲を超えるoptionがある場合は、そのtoolの正規documentationへ読者を案内する。 ## 経験と良い点・悪い点を添えて、はっきりすすめる practiceを率直に推奨し、経験、evidence、または具体的なtrade-offで裏付ける。有用なguidanceをhedgeの重ね書きで弱めてはならない。alternativeを扱う場合は、benefit、cost、適用条件を公平に示す。 rhetorical questionは控えめに使い、直後に答える。抑制の利いたhumorや、ときどき使う遊び心のある表現で個性を加えてもよいが、slangにはしない。特に有用なworkflowや将来の可能性を紹介する際は、根拠のある本物のenthusiasmを示す。 `Let's look at...`、`The real difference is...`、`Pro tip:` のような繰り返し使えるtransitionはvoiceの強化に役立つが、説明を前へ進める場合に限って使用する。 ## むだな言葉と、無理にくだけた言い方を外す 公開文章では、profanity、emoji、長い個人的anecdote、memoir調の脱線、slang、無理にcasualにした言葉を決して使用してはならない。変化の速い世界についてのcliché、「深く掘り下げよう」という定型句、中身のない結びのplatitude、`lol`、ALL CAPSによる強調を避ける。 buzzword、情報を伝えないfiller sentence、長すぎるintroduction、不要なpassive voice、大げさな言い回しを取り除く。英語では `utilize` ではなく `use` を使う。`please note that` や `it is important to note that` と前置きせず、要点を直接述べる。想定読者がすでに理解しているはずの内容を過剰に説明してはならない。 ## 見出しとコードブロックの書き方をそろえ、拾い読みしやすくする H1はdocument title専用とする。major sectionにはH2、subsectionにはH3を使用する。すべてのcode blockにlanguage identifierを付け、読者が実行できる例を優先する。 boldはkey termを最初に紹介する時、またはlist内で強調する時に使用するが、文全体をboldにしてはならない。italicsは短い補足、作品title、穏やかな強調に使用する。horizontal ruleはclosingまたはsignature sectionの直前にだけ置く。 linkの内容を明確にし、listの構造をそろえ、例はそれを支えるtextの近くに置く。Oxford commaを一貫して使用する。 ## レッスンとブログ記事を、問題・コード・次の一歩の流れで組む lessonまたはtutorialでは、次の順序にする。 1. 読者が学ぶ内容を1文で概説する。 2. contextまたはmotivationを2〜3文以内で示す。 3. code exampleを使って中核内容を教える。 4. lessonを関連topicへつなぐ。 5. contribution、質問、継続学習を読者へ促す。 blog postまたはarticleでは、短い問題またはopportunityから始め、なぜ今重要なのかを説明し、code、configuration、processを使った主要walkthroughを示す。続いて、より広いimplicationまたは追加のuse caseを検討し、将来を見据えたsummaryとengagementへの誘いで結ぶ。 ## 初心者向けの説明や新しいツールの紹介に合わせて、口調を変える beginnerへconceptを説明する時は、温かく、辛抱強く、協力的なvoiceを使用する。toolまたはworkflowを紹介する時は、limitationを率直に伝えながら、enthusiasticかつ実用的に書く。practiceは率直に推奨し、経験で裏付ける。 trade-offを公平に扱い、具体的なadvantageとdisadvantageを挙げる。将来のplanは、根拠のあるoptimismを持って書く。conclusionは簡潔にし、次の有用なactionを示し、参加しやすい雰囲気を作る。 ## 最後にコード例とリンクを見直し、次の一歩で締める 文章が実用的な問題から始まり、すぐに実例へ進み、断定するだけでなく説明していることを確認する。prerequisiteとcross-referenceがあり、technical termが正確で、exampleが実行可能で、名前を挙げたtoolに適切なcreditを示しているか確認する。 filler、不要なjargon、繰り返される導入、読者の必要量を超える説明を取り除く。heading、code blockのlanguage、link、emphasis、paragraph length、punctuationを検証する。次に試すこと、注意すべきこと、続きを学べる場所のいずれかを示し、次へ進める形で終える。