シェア:
){kind=small}
私はJavaScript開発者で、Vonageの開発者教育者です。長年にわたり、テンプレート、Node.js、プログレッシブ・ウェブ・アプリケーション、そしてオフライン・ファースト戦略に熱中してきましたが、私がいつも本当に愛しているのは、便利できちんと文書化されたAPIです。私の目標は、当社のAPIを使用するお客様の体験を、私がお手伝いできる最高のものにすることです。
コーディング・プロジェクトに関するテクニカル・ブログ記事の執筆
所要時間：1 分
コードを書くことは、書くことよりも簡単だ。 コードを書くのはコードを書くことの方が簡単だと言える。一方、自然言語はあらゆる種類の異なる方法で失敗したり成功したりする可能性がある。しかし、もしあなたが強力なコーダーなら、他のタイプの文章を書くのに成功するために必要なスキルのほとんどを持っている。
ブログ記事を書くのは、コードを書くのに似ている：
あなたはアイデアを練り、何もないところからそれを実現するまでの道のりを説明する。
誤訳を避けるため、構文規則に従う。
可能な限り簡略化しながらも、理解されるように冗長な表現に努めている。
について書いているとき についてコードについて書く場合、さらに使えるテクニックがある。しかし、読者があなたの記事から何を求めているかに集中することも役立ちます。技術的なブログ記事が他のタイプの文章よりも優れている点は、読者が何を求めているのかがたいてい明白であることだ。
問題は、テクニカル・ライティングがドライだということだ。それを和らげるために、さまざまな人がさまざまな戦略を持っているが、巧妙なトリックを使っても、その中心的な事実を変えることはできない。アルゴリズムや構文の抽象的な説明を読むのは難しい作業だ。脳は特に記憶-そして技術的な情報は、そのような連想の足がかりをほとんど与えてくれない。
これはテクニカル・ライティングだけに当てはまることではない。30分の講義や会議で起きているのに苦労したことはあっても、2時間の映画なら問題なく集中できる人なら、もうおわかりだろう。退屈するかどうかは、情報を受け取る人よりも、情報の見せ方に関係があるのだ。
なぜ人々は技術ブログ記事を読むのだろうか？ほとんどの場合、彼らはタスクを達成する方法を知りたいか、特定のトピックを深く掘り下げて知りたいのです。あなたの課題は、彼らのアテンション・スパンが尽きる前にそのニーズに答えることだ。
テクニカル・ライティングがほとんど常に改善されるのは、その量を減らすことである。記事の長さも文章の長さも同じです。使用するコード例にも言えることだ。技術情報を消費することは、私たちの脳にとって十分な挑戦です。情報の優先順位をつけ、重要でないものを取り除くことで、あなたのテーマを理解してもらうことができるのです。
残された文章を軽くするために使えるアプローチはたくさんある。効果的なツールをいくつか紹介しよう：
ユーモア
概念やコードの擬人化
画像（GIF、 円グラフではない)
インタラクティブな例
コード
箇条書きリスト
それらのテクニックの中には、書くこと自体に影響を与えるものもあれば、書くことから解放されるものもある。しかし、それらはすべて、数式やアルゴリズムを記憶する部分とは異なる脳の部分を使っている。記憶とは脳の各部分間のリンクでできており、読み進めているものを記憶することは、全体像を理解するのに十分な時間、精神的疲労を避ける鍵となる。
もしテクニカル・ライティングをあまりやったことがなかったり、満足のいくものが少なかったりするのであれば、テクニカル・ライティングを軽くする他の方法を試してみる価値があるかもしれない。コードに関するブログ記事では、他の場所と同様に著者の本物の声が重要です。あなたの声は、自然だと感じられるよく計画された戦略を持つことによって増幅される。
もちろん、ジョークを言ったり、GIFを加えたりして文章にスパイスを加えるのは構わないが、ある時点で、頭字語やハンガリー語表記の濁流に分け入らなければならなくなる。
専門用語を扱う第一の方法は、記事のスコープを正しく設定することだ。各専門用語の説明に複数の段落を費やさなければならないようなブログ記事は、おそらく一文の中で複数の専門用語を使用しているような記事と同じであってはならない。もし、多くの専門用語が混在していることに気づき、そのすべてを知っている人が一人もいないかもしれないと考えるなら、説明しすぎる可能性があるのではなく、その用語を正規の定義にリンクさせることができる。また、投稿を2つに分けて、省略したい人がいるかもしれない基礎知識をすべてカバーする前日譚をつけることもできます。
あなたの文章を辛口にしないためには、専門用語を記事の流れに組み込むことです。つまり
"
getDataは、データを取得する関数の名前です。その戻り値はoutput.何も返さないか、オブジェクトを返します。引数を2つ取ります。sourceが最初の引数でfilterは第2引数で、これはオプションである。"
このように、専門用語と自然言語を統合することができる：
「データを
sourceをgetDataにデータを渡すことでoutputオブジェクトを得ることができる。オプションでfilterを追加することもできます。マッチするものがなければgetDataは単にnull."
専門用語を形式的に扱いたくなるかもしれないが、それは文章を消化しにくくすると思う。一緒にペアプログラミングをしている人に、一緒に取り組んでいるコードについて話すときのような言い方をすれば、すぐに理解できるだろう。
自分が何をしているかを明示することなく、物語と変数名を行ったり来たりすることは、投稿の最終的なHTMLにある <code>タグによって可能になります。タグは、あなたが技術的ソリューションの特定の要素について話していることを視覚的に示し、支援技術でも認識することができます。特定の技術やツールの名前を太字にするなど、その他の技術用語の書式設定は、あなたやあなたの組織のスタイルガイドに任されています。
コードブロックのフォーマット方法も重要だ。最低限、シンタックス・ハイライトがあると便利です。これはコードを視覚的に理解しやすくするだけでなく、あなたの投稿の中で視覚的な面白さを提供します。コードブロック内のコードは、投稿用にすっきりさせるべきです。もしコード・コメントがブログの記事と同じことを説明しているのであれば、コードを少なく見せるために削除することができます。また、コードを読むために水平方向にスクロールする必要がないように、継承されたインデントを削除することもできる。
投稿をサブセクションにフォーマットすることは、情報を整理するのに便利で、使用しているブログプラットフォームによっては、投稿内でナビゲーションのショートカットを提供することができます。また、余談や箇条書きリストを使って記事を整理することもできる。ただ、フォーマットはやりすぎないこと。ほとんどのブログ記事は、たとえコードに関するものであっても、まだほとんどテキストであるべきだろう。
他のリソースへのリンクには、ちょっとした戦略が必要だ。もしあなたが役に立つ何かを見つけ、それがあなたの文章の流れの中で自然にリンクされるのであれば、文脈の中に余分な情報があることは有益である。しかし、文章中にリンクが多すぎて気が散ってしまうようなことは避けたい。リンクするものがたくさんある場合は、記事の一番上か一番下にリストを表示することができます。これには、チュートリアルの途中で読むのをやめて他の場所へ行くことを勧めないという利点もある。
ニュース記事など、ブログ記事よりも長い制作期間を要するコンテンツでは、画像の使用はごく一般的です。また、技術的な記事に少なくとも1つのメイン画像を掲載することも一般的です。この価値についてはすでに説明した。
技術的なブログ記事では、本文中に画像を使用することもある。これらは、テキストを分割するためのGIFのような、より視覚的な救済になるかもしれないし、説明的なものかもしれない。装飾画像で考慮すべき点は、法的な問題とアクセシビリティの問題だけです。画像の使用許可と配慮あるキャプションがあれば、問題ないでしょう。
技術的なコンセプトの中には、視覚的なデモンストレーションが有効なものがあります。セットアップの手順をスクリーンショットしたり、プロセスをGIFにしたりすることができます。また、ディレクトリ構造、出力例、あるいはコーディングしていないユーザーインターフェイスを投稿で見せることも役に立ちます。しかし、これらのことを完全に画像に頼らないことが重要です。画像の中にあるものは何でも説明するか、人々が同じものをローカルで作れるように十分な情報を与えるべきです。
コードの一部についてブログ記事を書くのであれば、コードについて説明することを計画すべきだ。読者にレポを紹介し、数行のナレーションをつけ、あなたのツイッターのハンドルネームを垂れ流すだけでは、とても有益なブログ記事にはなりそうもない。
ブログ投稿のコードが（大きなプロジェクトの一部ではなく）その目的のために特別に書かれたものである場合、それをコーディングしながら作成する手順を記録しておくと非常に便利です。そうすることで、記事のアウトラインができあがる。ブログの投稿やコードが完成した時点で、文字通り手順をメモしておくこともできる、 ほらあなたのアウトラインはすでに出来上がっている。コードが他の何かの一部分である場合、どの部分があなたの投稿のポイントにとって重要かを把握し、最初に説明する部分がその後に続く部分の依存関係になるように整理する。
もちろん、これらは一般的な提案だ。もしあなたが他人のコードを分解したり、本当に複雑なことを説明したりするのであれば、完成品から始めて、「彼らはどうやってそれをやったのか」というアプローチを取るのが素晴らしいかもしれない。
私が効果的だと感じているトリックは、コード例がそこにないかのように、コードの周りに物語を書くことです。これを別の方法で考えると、コーディングの面接で、実装の詳細を特定しないままソリューションの重要な部分を表現する必要があるようなものだ。人々はおそらく、GitHub のレポを見ただけでは得られない何かをブログの投稿に求めているのでしょう。 getData関数を追加します:" と書くだけでなく、コードブロック全体を自然な言葉で説明することも必要です。
コードを分割する方法は、説明とセルフ・ドキュメントの適切なバランスを取るのに役立ちます。もしコードを10行程度の重要なブロック（定型文や閉じ括弧ではないもの）に分けることができれば、それぞれを説明する2-3文の段落を書くことができ、いいペースを保つことができる。しかし、いつもそうできるわけではない。関数によっては巨大なものもある。
議論する必要があるコードが非常に長い場合は、人為的に分割することを検討してください。私は、次のようなプレースホルダー・コメントを残してこれを行うことを好む。 //INSTANTIATE VARIABLESと //FETCH VALUESのようなプレースホルダー・コメントを残すことで、コード自体の動作を変更する必要がなくなり、土壇場でバグを引き起こす可能性がなくなるからです。しかし、長いコードをモジュールや個別の関数に分割することも有効だ。抽象化を加えることで、あなたのコードはより議論しやすくなり、コード自体で得られる再利用性という同じ利点が、あなたのブログ記事でも共有できるようになる。また、同じようなテーマについて再び書く場合、それらの部分や、もしかしたらその説明も再利用できるかもしれない。
投稿の最後に、期待される結果が何であるかを確認するのは有効だ。もし読者がそれぞれのステップに沿ってコーディングしていてエラーが出るのであれば、おそらくすでに誤解があったのではないかと疑っているはずだ。しかし、必ずしもそうとは限りません。これでアプリケーションコードの準備は整いました。このチュートリアルに従ってAPI認証情報を設定するだけです。 このチュートリアルアプリを実行できるようになります。"
もし投稿の終わりまで来て、それ以上言うことがないのであれば、投稿の範囲を正しく設定した証拠です。もし、多くの注意事項を余分な段落に詰め込んでいるのであれば、コードや投稿の中で気になる点を戻って修正することを検討しよう。
技術的なブログ記事を書く最後の作業は、非技術的なブログ記事と同じです。技術的なブログ記事の場合、自動校正ツールからの提案を手動でチェックすることが重要です。コードブロックに編集を加える必要がある場合は、その後もコードが実行されることを確認してください。
VonageのAPIを使用した作業に関する技術的なブログ記事を書くことに興味がある方は、現在、以下の投稿を受け付けています。 開発者スポットライトプログラムへの投稿を受け付けています。
