作者：Christian Heilmann 翻訳：庄七
コード例は、あなたの投稿や記事を開発者にとってより関連性のあるものにするものです。それらは製品に関する数十ページの記事よりも意味があり、さらに重要なことに–それらは人々にあなたの製品をプレイするように誘います。技術記事を読むとき、最初のコード例まで直接スクロールすることさえよくあるかもしれません。
事実：StackOverflowのようなプラットフォームの成功は、説明を最小限に抑え、コードに話させることが理にかなっていることを示しています。これには、多くの開発者がもはやコードの「理由」に煩わされず、「方法」に固執し、コードをコピーして貼り付けて自分の製品に使用するという不幸な影響もあります。私はこれらの人々を「FullStackOverflow開発者」と呼んでいます。
例を使って問題を解決する
私が最も嫌いのは、何も有用なことをしない「hello world」の例です。代わりに、私の目標は実際の問題を解決できるコードを提供することです。
事実：「Hello World」のコードは人々にコードを書く方法を教えますが、それを使って問題を解決する方法は教えません。
優れたコード例は、「この技術はどのように私の問題を解決するのに役立ちますか？」という質問に答えるべきであり、「これをどのように使いますか？」という質問に答えるべきではありません。「これをどのように使いますか？」という質問は、ドキュメントによって回答されるべきです。コード例は、製品を使用することについて人々を興奮させ、詳細を理解するためにドキュメントに誘い込むべきです。
したがって、自分でドキュメントを読むことから始めるのではなく、このツールが何ができるかを確認し、この技術があなたを助けることができる、常に解決したいと思っていた問題を見つけてください。次に、製品でそれを解決し、コードを例としてあなたが行ったすべてのことを説明します。これは、製品ドキュメントが効果的であるかどうかを確認するための優れた方法でもあります。開発者の擁護者として立ち往生し、効果的なドキュメントを見つけることができない場合、それは良いことです。不足しているドキュメントを書くことで製品をどのように助けることができるかの最高の例があります。
動作する例を示す
コード例で最初に示すべきことは、動作する実装です。リンクをクリックしたり、テーブルのデータで遊んだりして、そのものがどのように機能するかを見ることほど強力なものはありません。それがどのように機能するかを読者に伝えることは一つのことです–読者が自分で試して、それが機能しているのを見ることははるかに意味があります。
ヒント：説明しているコードが、より大きなインターフェースの一部である場合、ファイアウォールの背後にある場合、または認証が必要な場合でも、画面を記録することでそれがどのように機能するかを示すことができます。これらは影響が少なく、「偽物」とみなされるかもしれませんが、何もないよりはましです。
例は機能するべきですが、美しくて滑らかでもあるべきです。多くの例は満足のいくものではなく、実際に多くの基本的なユーザビリティの原則に違反しています–貧弱な第一印象を与えないでください。
必要な環境を説明する
人々にあなたのコードに興奮させた後、彼ら自身の環境で動作させることができないようにすることを避けたいと思います。これにはいくつかの方法で対処できます：
-
防御的なコードを書く：依存関係にアクセスしようとする前にチェックします。
-
オンラインおよびHTTPステータスをチェックする：コードがWebサービスからデータを取得する必要がある場合、ユーザーがそれを実行するにはオンラインである必要があると言います。たとえば、私のJavaScriptの例のいくつかがオフラインで、またはローカルサーバーを実行せずに動作しないという多くの苦情を受けました。明らかに、ライブデータが必要であること、そしてセキュリティ上の理由から、JavaScriptの特定の機能はHTTPSを介してアクセスした場合にのみ機能し、ファイルシステム上では機能しないことを説明しませんでした。
-
必要なものをリストアップする：依存関係が何であるかを言います。たとえば：「NodeとNPMが必要」または「Microsoft Edge 85以降で実行」。サードパーティの依存関係が必要な場合は、読者のためにそれらをインストールするための優れたチュートリアルを見つけ、依存関係の名前をそれにリンクします。
-
簡単なテストスクリプトを提供する：正しいセットアップをチェックします（例については、GeoMakerのテストファイルを参照してください）。
-
デモ用の開発者キーを提供する：ただし、人々に、コードを実装するには、自分自身のキーが必要であることを明確に伝えてください。キーを申請するためのリンクを提供してください。
コードを実行するときに人々が間違える可能性のあるすべてのことを予測することはできませんが、これらはフラストレーションを防ぐための良い方法です。これは、コード例の重要な部分、つまりコピーと貼り付けを許可することにつながります。
効果的なコピーアンドペーストコードを書く
コピーと貼り付けはおそらく、コードを学ぶ最も一般的な方法です。指が出血するまでドキュメントを書くことができますが、最大のユースケースは、開発者がコード例をチェックし、それをコピーして貼り付け、立ち往生するまでいじくり回し、そしてドキュメントを読み始めることです。
事実：クリーンなコピーアンドペーストの例を書くことは非常に重要です。コードに追加する悪いコーディング習慣はすべてコピーされ、実際の実装の一部になります。
コピーアンドペーストに役立たない例は、役に立たないだけでなく、あなたの評判にとって壊滅的であり、実装者にとって非常にイライラさせるものです。以下のポイントを確認してください：
-
すべてのリソースにリンクする：画像、CSS、およびスクリプトリソースをローカルまたは相対位置にリンクするのではなく、Webの場所にポイントします。人々はコードをコピーしてローカルプロジェクトに貼り付け、依存関係をダウンロードしません。
-
最初から完全なスクリプトを提供する：人々は大きなスクリプトの塊をコピーして貼り付け、他の部分が欠落していることに気づかずに、それらが機能しないと不平を言います。
-
コードを検証して保護する：コピーアンドペーストのコードは優れたものでなければなりません。コードが他のコードとうまく連携し、警告やエラーを引き起こさないことを確認してください。
ダウンロード可能な例
あなたの例では、デモコードをダウンロードするためのzipファイルを提供することが、あなたが最初に行うことの一つであるべきです。読者にダウンロード、解凍、そしてあなたと一緒にコーディングするように依頼することができます。これは、スクリーンキャストや動画チュートリアルでよく機能します。いずれの場合も、読者のハードドライブにそれを思い出させるものがあるため、記事を読者の記憶に残します。
デモコードの圧縮バージョンを提供することは、変更のたびにデモを再パッケージする必要があるため、面倒な場合があります。幸いなことに、GitHubなどのホストされたコードソリューションは、あなたのためにこれを自動的に行います。
クリーンで賢い例を書く
私は繰り返しますが、あなたのコード例は、あなたがこれまでに書いた中で最もクリーンで、最も賢いコードであるべきです。人々を始めさせ、最短のコードを作成したことで即座に称賛を得るために、迅速で汚いソリューションを示すのは非常に誘惑的です。しかし、それはプログラマーが互いに感銘を与えるために行うことであり、デベロッパーエバンジェリストが行うことではありません。
あなたは、あなたが宣伝している製品で優れたソリューションをどのように書くかを示したいと思っています。あなたが取るあらゆるショートカットは、コピーされ、実際のプロジェクトで優れたコードを書かない理由として使用されます。これはここでの私たちの目的ではありません。
代わりに、デモコードは、学術的な演習としてではなく、コンテキスト内で最良の開発プラクティスを宣伝して示すことができます。モジュールパターンを使用してスコープを保護し、クロージャーを巧妙に使用するJavaScriptを示すことで、これらのアイデアとのクロスコネクトが可能になり、一部の開発者にそれらをコーディング習慣の一部にすることができるかもしれません。
コードジェネレーターを構築する
ソリューションに追加する良いタッチは、実装者がいくつかのパラメーターを追加し、ボタンをクリックして、必要なコードを取得できるコードジェネレーターです。これは驚くほど強力です。
一部の人々が実際の実装テクニックを決して学ばないという危険があります。一方で、これらの読者はとにかくそうする可能性は低いでしょう。いずれにせよ、製品を見る人がより多くなります。
コードとデモをホストする
個人的なサーバーにコードとデモをホストすることは魅力的かもしれません。私自身も何年もそうしてきました。これの利点は、このサーバーを制御できることです。欠点は、このサーバーを維持するのはあなた次第であることです。そして、あなたはサーバー管理者としてではなく、宣伝に時間を費やしたいと思っています。
警告：何年にもわたって、私はサーバーを遊び場として使用してきました。その状態を見ると、それも苦痛でした。私の過去のコードのいくつかは優れた攻撃ベクトルになり、2006年の私のAJAXデモの一つは、深いフォルダーにスパムブログがインストールされることになりました。これはまた、Googleが私のドメインをブロックし、他にも多くの問題を引き起こしました。
サーバーを持つことは良いことですが、あなたやあなたのコードを見ている人々にも、それがスクラッチパッドであることが明らかでなければなりません。そこのコードはいつでも消える可能性があります。より保守しやすく制御された方法でデモとコード例を公開することを検討するのは理にかなっています。
バージョン管理
私は、多くのトラブルを防ぐ最初のことは、すべてにバージョン管理を使用することであることを発見しました。Gitは一般的なものですが、OneDrive/Dropbox/Box/Google Driveまたは任意のフォルダーに製品を配置することも良いアイデアです。あなたは常に台無しにし、ファイルの最後の変更に戻すことができるのは素晴らしいことです。
*Gitを使用することは、「test123-safety-still-works」という名前のZipファイルを作成したり、各フォルダーがバージョン名と日付であるフォルダー構造を作成したりしないため、ハードドライブのスペースを節約できることも判明しています。
バージョン管理システムを使用することは以前は威圧的でしたが、Gitの登場とGitHubやGitlabなどのホスティングソリューションの登場により、事情は簡単になりました。Gitのもう一つの実用的な効果は、コミットにコメントを付けなければならないことです。このようにして、潜在的なメンテナーや教えたい人にコードを説明するために使用できる変更履歴を作成することができます。
また、GitHubプロフィールのようなオープンソースのホスティング機関を持つことは、人々があなたのコード例とコースを見つけ、それらに貢献し、あなたにフィードバックを与えるための優れた方法です。このようなプラットフォームで問題として報告された問題は、電子メールやソーシャルメディアプラットフォームを介したランダムなフィードバックよりも理解しやすいです。あなたがどこにキャンプを設けても、無料のプランに依存せず、プラットフォーム上でより良い、サービスされた存在を得ることが重要です。これらは高価ではなく、特定の制限に達したり、プラットフォームが変更されたりして、コードにアクセスできなくなる状況に陥りたくないでしょう。
ヒント：これは重要なポイントです。あなたが選択するどのプラットフォームも、バックアップと人々があなたを見つけるための方法でなければなりません。あなたは、いつでもすべてのデータのバックアップを取得して他の場所に移動することができない場所にものをホストするべきではありません。私たちの市場は常に変化しているので、あなたのすべての作業とともに、すぐに消える可能性のあるリソースに依存しないようにしてください。
事実：Gitベースのコード共有プラットフォームは相互に互換性があるように設計されているため、これはあなたにある程度の安心感を与えるはずです。これらのプラットフォームは、YouTubeや同様のサービスがメディアストリーミングのために最適化されているのと同じように、コードの提供と配信のために高度に最適化されています。
人々にコードについて語るときの私の主な不満の一つは、チュートリアルとドキュメントには実行可能なコードと読みやすいコードの両方が必要であることです。私は何年もかけて、ブログプラットフォームや本で正しく表示されるように、よく動くコードを変更してきました。このようなプラットフォームに例をホストすることで、これはまったく問題になりません。
自動ホスティング
コードホスティングプラットフォームは、コードを保存し、人々がアクセスできるようにするだけでなく、人々があなたのコードを取り、コピーを取り、そこで必要に応じて変更することができる組み込みのフィードバックメカニズムも備えています。
あなたにとっては、ウィキとドキュメントを追加するオプションもあります。さらに重要なことに、これらのプラットフォームのほとんどは、コードをホストするだけでなく、それを実行することもできます。これには当然いくつかの制限があります。これらのプラットフォームのほとんどでHTML、CSS、JavaScriptを表示することができます。サーバーサイドの実行可能コードはホストする場所を見つけるのが難しいですが、ソースコードとともに完全なアプリケーションをホストすることを許可するいくつかのプラットフォームもあります。
ほとんどのプラットフォームには、Gatsby、Jekyllなどの静的サイトジェネレーターが含まれています。この本をオンラインで読んでいる場合は、これが私が使用しているものです。ここのテキストはmarkdownで書かれており、GitHubページとJekyllを使用してHTMLを生成しています。
コードサンドボックス
コードと製品をホストするためのプラットフォームに加えて、コードサンドボックスサービスも利用できます。これらのサービスを使用すると、コード例を書き、ソースコードと実行可能性の両方を世界と共有することができます。これらのプラットフォームはエディターと結果を見る場所であり、このユースケースのために高度に最適化されています。追加のボーナスとして、ブログ投稿や記事にコード例を埋め込むこともできます。
JSFiddleは最初のものの一つでした。その後、JSBinで人気になり、Codepenはこの分野のもう一つの大きなプレーヤーです。それらは基本的なWebコードの記述だけでなく、プリコンパイラも提供するため、抽象化ライブラリの設定とカスタマイズで説得する必要なく、特定の抽象化がどのように機能するかを人々に示すことに集中することができます。MozillaのWebドキュメントチームで働いていたとき、私たちは人々が説明された場所で直接コードを試すことが大きな勝利であることを発見しました。
トレーニング中に、会社の方針によりコンピューターにソフトウェアをインストールできない状況に遭遇する可能性があります。これらのサービスを使用することで、参加者に必要なのはブラウザと接続だけであるため、コースを実行し続けることができます。
ライブコーディング環境
これらのプラットフォームの多くには、Office 365やGoogle Docsを使用してテキストの共同作成を行うように、他の人とリアルタイムで開発できるデモモードとライブモードがあります。Code Sandbox、Glitch、その他多くのプラットフォームがこれに優れており、CodepenとJSBinもこのユースケースに対応するために機能セットをアップグレードしました。
ライブコーディング環境は、ワークショップや講演の予約を検討している潜在的なクライアントに何かを示すのに最適です。それらはまた、シンプルなユースケースを作成し、世界中のチームと問題を解決するための優れた方法です。驚くことではありませんが、それらは面接でもよく使用されます。
コードショーケース
これらのプラットフォームのいくつかは、コード例を中心にコミュニティを構築するのに優れた仕事をしています。たとえば、Codepenは、講演に追加し、それらを可能にする技術を説明するための例の宝庫です。ただし、人々にクレジットを与えることが重要です。また、そこでクールなものを示すことで参加し、自分自身の評判を構築することもできます。
これらの例は多くの場合、最新の技術を使用しており、デベロッパーエバンジェリストとしてのあなたが、潜在的な他のユーザーにその価値を示すための優れた方法です。そして、結局のところ、それらは遊ぶのが楽しいです。私はショーケースサイトを通じて情報を共有しているかなり興味深い人々を見つけました。いくつかのデモは、レンダリングエンジンに特定の負担をかけるため、私が働くブラウザーのパフォーマンスを向上させる役割を果たしています。
転載をご希望の場合は、出典を明記してください：デベロッパーリレーションズ »
