デベロッパーアドボカシーマニュアル（9）：ブログと記事の執筆

作者：Christian Heilmann 翻訳：庄七

ウェブ執筆は専門的なスキルです。多くの場合、人々はオンライン記事やブログ記事を書くときに他のメディアのルールを適用します。成功率は低いです。

ウェブ上のテキストは孤立して公開されるのではなく、ブックマーク、リンク、参考文献としてウェブ全体に広がることに注意してください。したがって、テキストを消化しやすく、引用可能で、繰り返し可能なチャンクに分割し、記事のタイトルとファイルの見出しを全文なしで機能させることが重要です。

事実：これはアクセシビリティの利点でもあります。スクリーンリーダーのような支援技術を使用すると、文書全体を1つの大きなブロックとして聞くのではなく、見出しで文書をナビゲートすることができます。

シンプルは愚かではない

シンプルなテキストを書くことは大変な作業です。印象的な記事を書く方が簡単です。人々は複雑な言葉や参照を使って聴衆に印象を与えようとするのをよく見かけます。小説や歌詞を書くときはこれはいいことであり、言語を弄するのはたくさんの楽しみがあります。しかし、ウェブ上では、特に開発者エバンジェリズムにおいては、できるだけ理解しやすくすることが目標です。シンプルなテキストのこれらの特性を考えてください：

シンプルな用語で書くには、多くの作業とトピックの徹底的な理解が必要です。シンプルな言語で説明するには、トピックに精通している必要があります。シンプルな言語で説明できない場合は、おそらく自分自身がトピックを完全にマスターしていない可能性があります。
可能な限りシンプルな用語で説明することで、可能な限り広い聴衆に到達することが保証されます。
シンプルな言い回しは、母国語でない人々が全体の内容を理解し、おそらく翻訳ツールを使ってそれを彼らに役立たせる機会を与えます。
短くて消化しやすい文は読みにくいものではありません。最初に一目見たときも威圧感がありません。テキストを読む前にスキャンすることは、ウェブ上で非常に一般的なパターンです–特にモバイルデバイスでは。

警告：ただし、複雑なことをシンプルな用語で説明することと、威張るように聞こえることの間には線があります。「単純化」の道を行きすぎていると疑われる場合は、この問題を避けるために他の人に記事を見てもらってください。書いたものを読み返し（間に休憩を入れて）、反復するたびに簡単にしてください。

実生活のオブジェクトやシナリオとの比較は、複雑な問題を単純化するのに役立ちます。

例：Yahooの「Hack Day Open」で、私はハックデイとオープンAPIの概念に非常に混乱している複数のメディア関係者と話をしました。当時、これらはまったく新しいものでした。私はこのように説明しました。「Yahooが自動車会社だったら、最新モデルがここで分解され、部品で遊ぶことを許可するでしょう。おそらく、彼らはそれらを組み立てるクールな新しい方法を見つけるでしょう。それが、自動車をより環境にやさしく、効率的にするために必要な突破口です。」

ヒント：オンラインで書くときによく使用するツールの1つはHemingwayです。hemingwayapp.comで試すことができます。これは、テキストがどのくらいの読解年齢を必要とするかの指標を与えるオンラインエディターです。文章が長すぎたり、単語が複雑すぎたりするなどの一般的な問題にフラグを立てます。

シンプルかつ直接的に–砂糖で包まないでください

見出しと導入テキストはブログの最も重要な部分です。どちらも将来この投稿を見つけやすくなるかどうかを決定します。新聞は、キャッチフレーズや暗示を含む機知に富んだおかしな見出しを書くように私たちを条件づけてきました。これは楽しいことですが、あなたはすでに新聞を買ったことを知っている状態でそれらを読みます。ウェブの見出しはリンク、ブックマーク、ソーシャルメディアの共有になります。したがって、他のテキストなしで意味を持つ必要があります。技術的なブログ投稿の場合は、投稿の内容を明記してください–賢すぎないようにしてください。ポップカルチャーの参照はさらに悪いです。なぜなら、これらは他の文化にうまく翻訳されないからです。自分に尋ねてください：一分間創造的で機知に富んでいたいですか、それとも数ヶ月間効果的な情報を提供したいですか？

ブログ記事はラジオのニュース項目のようになるべきです：

どのブログの冒頭でも、何が起こったか、どこで起こったか、どのように起こったかを述べます。
ブログの内容を説明し続けます。
そして、詳細に入ります。

これにより、混乱を防ぎ、興味のある人々がより多くの情報を得ることができます。ソーシャルメディアやあらゆる場所で共有されるとき、人々は自動的な方法であなたの文書にリンクし、ブログのタイトル（HTMLのタイトルまたは文書の大見出し）を使用する可能性が高いです。あなたのタイトルが文脈から外れて意味がないように見えると、それらをクリックする人はあまりいません。

ヒント：ほとんどのソーシャルネットワークには、リンクを自動的にそのタイトルと最初の画像に展開するリンクプレビューがあります。これは重要であり、活用する価値のある強力なものです。選択したソーシャルメディアプラットフォームで合理的で興味深いプレビューを取得するために、記事に必要なメタタグを理解してください。

コンテンツの長さ

オンライン使用のための技術文書は、コンテンツを短く、要点に絞ることについてです。人々は忙しく、事実にたどり着きたいと思っています。

ヒント：良い記事を書くには、書き、読み、不要なものを削除し、再び読み、さらに削除し、繰り返します。もう削除できなくなったら、発行可能な品質に達しています。

たくさん話したい場合は、なぜそれを複数の記事に分割しないのですか？これにより、最初の記事の最後で、次の記事が数日以内に公開されることを告知し、ブログに繰り返し訪問者をもたらすことができます。

マルチメディアコンテンツを追加する

可能であれば、ブログに関連するメディアを含めてください。紹介写真は目を引き、脳を誘い込んで起こっていることを読ませます。ビデオ、オーディオ、スライドショーの埋め込みが今ではコピーアンドペーストと同じくらい簡単になったのは幸運です。

マルチメディアを埋め込むと、情報が消化しやすいチャンクにまとめられます。また、訪問者が最初に記事をスキャンし、後で残りを読む（ビデオを見たり、ポッドキャストをダウンロードしたりする）ことも可能になります。また、読むのが難しいが、聞いたり見たりするのは完全に可能な人々を助けます。

マルチメディアを埋め込むときは、説明的なテキストも書くようにしてください–画像には良い代替テキストが必要で、ビデオには少なくともそれらが表示する内容の説明が必要です。

ヒント：スライドは、テキストの代替手段やメモを提供することで、はるかに効果的に機能します。多くのスライドホスティングプラットフォームは、スライドのHTMLスクリプトを自動的に作成します。個人的には、メモから始めて、これらのメモに基づいてスライドを作成します–このようにして、スライドからリンクすることができるHTMLバージョンが常にあります。

コンテンツの構造化

コンテンツを構造化することは非常に重要です。読者があなたの情報を読むことを決定する前に記事の構造をスキャンするための目印を提供することは、人々が忙しいので素晴らしいことです。

これは、階層的な見出し構造を使用することによって行います。これはまた、スクリーンリーダーなどの支援技術を使用する人々があるセクションから別のセクションにすばやくジャンプするのに役立ちます。見出しにIDを追加すると、人々は文書の特定の部分にブックマークを付けたり、友人にリンクを送信して直接行きたい場所に誘導したりすることができます。

ヒント：見出しのアウトラインから始めると、はるかに速く書くことができます。記事の異なる部分を異なる時間に書くことさえできます。多くの場合、記事のある部分で立ち往生し、ライターズブロックに直面したとき、一時的にそれをスキップして、より簡単またはより馴染み深い別の部分を書きます。

構造化された記事はまた、短い文を使用することを意味します。それは、一度に1つのことを扱う段落を意味します。それは、ステップバイステップのプロセスを説明したり、既存のコンテンツの概要を与えたりするためにリストを使用することを意味します。大きな文書の場合は、人々が直接必要な場所にジャンプできる目次も提供することを意味します。

コンテンツにタイムスタンプを付ける

「賞味期限」を過ぎた食品を食べると、病気になります。出版物にタイムスタンプを付けないと、将来の技術標準で有害であっても、永遠に正しいと見なされます。それらは引用され–時々悪く–再引用され、真実として取られます。

例：私がウェブ開発を始めたとき、レイアウトのためのテーブルはウェブサイトを構築する唯一の方法でした。Netscape3やIE4、その他の「楽しい」ブラウザでこれらのテーブルを機能させるには、多くのトリックを知る必要がありました。私はこれをどのように行うかについていくつかの記事を発表しました。今や、テーブルレイアウトはウェブ開発にとって逆行的であり、実際にレンダリングが遅くなっています。私の記事に日付がなければ、おそらく人々はまだそれらを関連性があると考えているでしょう。すべての「CSSレイアウトは難しすぎる」記事は確かにそれを示唆しています。

私たちの技術環境は驚くほど速い速度で進化しています。半年前の「ベストプラクティス」は、現在では「有害」と見なされる可能性が高いです。ですから、読者が文書のアドバイスに従う前に、たとえ今でも、文書がいつ書かれたかを知っているようにしましょう。

証明するために引用する

このセクションのもう一つの重要なポイントは、他の情報源を引用し、あなたが構築しているコンテンツにリンクすることです。（もちろん読んだ後に）他の情報源を引用することで、あなたのアイデアと事実が検証されます。読者はあなたを盲目的に信頼する必要はありません–比較することで自分の考えを形成することができます。

先回りする

開発者エバンジェリストとして、あなたは技術者と外部の世界、そして技術者とあなた自身の会社の間の不足しているリンクであることを忘れないでください。これにより、PRを行っている他の会社の部署が果たすことのできないタスクが与えられます。これを先回りの執筆と呼んでいます。

私の意味するところは、製品について話すとき、それらを「販売」してはならないということです。代わりに、あなたの仕事は開発者にそれらに興味を持たせ、彼らをあなたの販売員にすることです。ここでの主なタスクは、通常のセールスピッチをした場合に得られるフィードバックを予測し、それが起こる前に答えることです–先回りの執筆。

砂糖で包んだり、ネガティブな情報を隠したりしないでください：代わりに、なぜそれが起こるのか、それが起こったときに何をすべきなのか、そして問題を修正する責任者にどのように報告するのかを説明してください。

事実：開発者として、私たちは懐疑的な集団であり、何年にもわたる破られた約束によって硬くなっています。どんな製品の説明でも、興奮しすぎて肯定的な説明をすると、私たちは「これを手に入れなければならない」とは思わず、「さて、何が引っかかっているのか」という質問を引き起こします。

これにより、開発者は反社会的に見え、クラシックなピッチをして否定的なフィードバックの弾丸に直面しているマーケティング担当者やPR担当者にとって、これは信じられないほどストレスフルになる可能性があります。あなたの仕事は、このフィードバックの一部を予測し、あなたの執筆でそれを認めることで状況を和らげることです。これはPRやマーケティング部門への難しい販売になるかもしれませんが、良い点と悪い点についてオープンにすることで、メディアによって文脈から外され、PR部門に多くの仕事を与える多くの混乱したまたは悪いフィードバックを避けることができると彼らに説明することができます。

ヒント：最近では、PR部門も先回りの執筆の哲学を採用し始めています。私がいつも見ているプロセスの1つは、今後の製品リリースのための「無礼なQ&A」を作成することです。製品のチームは、意図的に無礼で問題のある質問のリストを作成し、それらを処理する方法についてワークショップを開催します。本当のリリースでこれらの質問が出てこなければ、素晴らしいです。しかし、出てきた場合は、準備ができています。

否定的なフィードバックは多くの場合いくつかのカテゴリーに分けられ、それらのすべては通常「インターネットの強者」の方法で作者を提示します。

事実：一部の人々は、トラブルを引き起こしたり「システムと戦ったり」したり、不必要に議論を延長するように人々を挑発したりするために否定的なフィードバックを使うのが好きなトロールですが、他の人々は繰り返しの失望によって無意識のうちにそうしています。維持するのは難しいバランスです。真のトロールは単に無視するか、「トロールに餌を与えない」という格言のようにすべきです。しかし、人々はあまりにも早く投稿したり怒ったりすることで「偶然のトロール」になる可能性があります。否定的なフィードバックを無視するのは誘惑的かもしれませんが、時々言い回しはあなたが解決できる別の問題を暗示しています。

否定的なフィードバックのいくつかのカテゴリーとそれらを先回りするヒントを以下に示します：

これは単に私には機能しない：あなたが話している製品やデモを実行するために必要な環境を必要な詳細で定義するようにしてください。
これはY社の製品Xと同じです：多くの場合、これは競合他社のファンです。あなたの製品が他の製品と非常に似ていることを言及し、それらをリストアップしてください。それらがどのように異なるか、なぜあなたの製品が単なるコピーではないかを詳細に説明してください。他の製品について知っていることを示すことで、あなたが勉強したことを証明し、それでも話す価値があると考えていることを証明します。あなたが研究をしていなかったことを人々に見つけさせないでください。
いいですが、私は決して使わない、誰も必要としません：製品がどの問題を解決するかを詳細に説明してください。これが現在一般的な問題ではなく、将来の問題である場合は、人々が製品をどのように好むかについてのフィードバックを求めてください。また、彼らがこの問題に直面したときに、製品が準備されていて良い状態になるようにする機会であるとも言ってください。
あなたの製品Yがまだ壊れているときに、なぜこれに時間を無駄にしているのですか？：あなたの執筆が記事の範囲を設定するようにしてください。1つの製品について詳しく話します。幸運なら、他の人がそのようなコメントに答えて、それがトピック外であることを指摘するでしょう。そうでない場合は、それがトピック外であることをすばやく答え、その人が他の製品に対する不満を発散できる別のスレッドや議論を指摘してください。
私はこれが好きですが、テストする時間がありません：人々が簡単なクリックで試すことができるシンプルなフィードバックメカニズムを備えたいくつかのデモとコード例を準備し、おそらく簡単なアンケートも提供してください。

これらは、完全な開示を使用して悪いフィードバックを先回りする方法のいくつかの例にすぎません。さらに多くの例がありますが、これに対処する良い方法を見つけると確信しています。あなたが書く資料をよく見て、悪いフィードバックが起こる前にそれを予測してみてください。より明確な情報を提供することで避けることのできる誤解は、潜在的に別の満足した顧客になる可能性があります。

行動の呼びかけとより多くの情報

記事を終えたら、行動の呼びかけで終わるのが理にかなっています。使用するリソース、より多くの情報を見つける場所、およびあなたまたはあなたが書いた製品の背後にあるチームに連絡する方法を繰り返す必要があります。

転載をご希望の場合は、出典を明記してください：デベロッパーリレーションズ »