DigitalOceanコミュニティチュートリアルの提案と概要を作成する方法

getdocs

2年前

序章

だからあなたはDigitalOceanのチュートリアルを書きたいのです！ DigitalOcean編集チームはあなたのような作家をサポートするためにここにいます：コミュニティの他の人と知識を共有したい開発者とエンジニア。

DigitalOceanは、提出されたすべてのチュートリアルを受け入れることができないため、執筆を開始することを承認する前に、提案を確認するようお願いします。受け入れられるかどうかを知る前にチュートリアル全体を書いてほしくないので、詳細な概要をお願いします。そうすることで、私たちはあなたが何について書きたいかについて良い考えを得ることができ、あなたが書き始める前にあなたにいくつかのフィードバックを提供することができます。ドラフトを修正するよりもアウトラインを修正する方がはるかに簡単なので、記事の構造を変更するのに最適な時期です。アウトラインが適切に配置されていれば、書き込みプロセスをよりスムーズに進めるためのフレームワークが得られます。

この記事では、チュートリアルのアイデアの提案と概要を作成する方法を説明します。最初にコンテンツの作成に役立つ準備を行い、読者に達成してもらいたい目標を決定してから、そこに到達するための手順を定義します。書き込みプロセスは反復的であるため、前の手順に戻る場合がありますが、このフレームワークはアウトラインの作成に役立ちます。

ステップ1—フォーカスを定義する

最初に決めることは、あなたが何について書きたいかということです。多くの場合、このアイデアは1つの名詞から始めます。たとえば、Nginx、Helm、Reactなどです。次に、名詞に付随する動詞を見つけます。ユーザーに製品で何をしてもらいたいですか？言い換えれば、読者にとっての学習成果は何ですか？この段階で、焦点をライターからリーダーに移します。「何について書きたいの？」の代わりに質問は「読者は何を達成したいのか」になります。正しい動詞を見つけることはその質問に答えます。「学ぶ」や「理解する」などの動詞は、測定可能な結果が得られないため、チュートリアルには適していません。代わりに、次のような動詞を検討してください。

インストール
作成
構成、設定
統合
配備
モニター
テスト
安全
自動化
トラブルシューティング

ほとんどすべてのDigitalOceanチュートリアルは、「How To」という単語で始まります。これは、適切な動詞を選択するための手がかりになります。以下は、適切な動詞を持つ名詞を使用する優れたチュートリアルタイトルです。

これにより、読者の学習目標が明確に示され、タイトルの定義にも役立ちます。これらは両方とも、私たちがあなたの提案で求める情報です。

トピックを適切に定義したら、誰のために書いているかに注意を向けることができます。

ステップ2—対象者を決定する

チュートリアルを計画するときに考慮すべき次のことは、誰がそれを読むのかということです。チュートリアルから最も恩恵を受けるのは誰ですか、そして彼らはすでにどれだけ知っていますか？彼らがすでに知っている量によって、提供する必要のある背景情報の量が決まります。これは、チュートリアルの長さに影響します。

たとえば、チュートリアル Ubuntu 20.04を使用したサーバーの初期設定は、背景知識がほとんどないことを前提としています。 root とは何か、およびSSHキーがどのように機能するかを説明します。これは、初めてサーバーをセットアップする読者にとって適切な対象者です。

チュートリアルDigitalOceanKubernetesでFlaggerを使用してリリースを段階的に配信する方法は、はるかに経験豊富な読者を想定しています。読者がKubernetes、Helm、Nginxに精通しており、これらすべてのテクノロジーを使用するようにクラスターが既に構成されていることを前提としています。これにより、作成者はこれらの製品の構成をスキップして、チュートリアルの主題であるFlaggerに集中できます。

注：前提条件のチュートリアルは、提案されたチュートリアルが進んでいる場合に役立ちます。 DigitalOceanには、3,000を超えるチュートリアルのライブラリがあり、提案しているチュートリアルの前提条件として使用できます。 Flaggerチュートリアルには、Kubernetes、Helm、Nginxなどを設定するための前提条件があります。

DigitalOceanチュートリアルの場合、通常、幅広い対象者よりも狭い対象者の方が適しています。 Kubernetesの負荷分散設定を構成する方法について書いている場合、オーディエンスにはKubernetesを使用するすべての人を含める必要があると思うかもしれませんが、十分なクラスターと十分な数のKubernetes管理者だけにオーディエンスを集中させると、より便利なチュートリアルが得られます。ロードバランサーの微調整を必要とするトラフィック。言い換えれば、より高度な聴衆。

これは、チュートリアルに幅広い魅力がないことを意味するものではなく、他のスキルレベルの読者にアピールするための追加のコンテキストを提供できます。ただし、聴衆を狭くしておくと、計画段階が簡単になります。

オーディエンスを定義すると、カバーする必要のあるコンテンツの量、つまり範囲がわかります。

ステップ3—範囲を決定する

聴衆と同様に、DigitalOceanチュートリアルの範囲は狭くする必要があります。単一のタスクに集中するようにしてください。「ReactフロントエンドとMySQLデータストアを使用してノードアプリケーションをデプロイする方法」のチュートリアルには、多くのコンポーネントと多くの手順が含まれています。むしろ、ノードアプリケーションをデプロイする方法に関するチュートリアルを見たいと思います。最初のチュートリアルが正常に公開されたら、最初のチュートリアルを前提条件として別のチュートリアルを提案し、その方法でより複雑なソリューションを構築できます。

読者がステップをうまく再現できるようにしたいので、狭い範囲も望ましいです。 6つの異なるサーバーを含む監視に関するチュートリアルを作成することもできますが、リーダーはその数のドロップレットを設定する必要があり、不便または高価になる可能性があります。たった2つのドロップレットで同じ目標を達成できる場合、読者はより大きなネットワークに外挿することができます。

同様に、複数の異なるテクノロジーを必要とするチュートリアルは避けてください。（たとえば）「TravisCIを使用してFlaskアプリケーションをデプロイし、DebianでNginxを使用してGrafanaを監視する方法」に関するチュートリアルは、これらすべての正確なテクノロジーを使用している読者にのみ役立ちます。これらのテクノロジーの1つが置き換えられたり、サポートされなくなったりした場合、チュートリアルの寿命が制限されます。このガイドラインの例外は、LAMPやElasticなどの特定の技術スタックの使用法を示すことを特に目的としたチュートリアルです。

チュートリアルの制限を定義したら、アウトラインを使用してチュートリアルのフレームワークの作成を開始できます。

ステップ4—タスクのブレインストーミング

何について書きたいのか、誰のために書きたいのかがわかったので、アウトラインをまとめることができます。そのプロセスの最初の部分は、解決しようとしている問題に関係していることをブレインストーミングすることです。関係する全体的なタスクと、実行する可能性のある個々のプロセスについて考えてください。たとえば、 Ubuntu にNginxをインストールする方法に関するチュートリアルを書いている場合は、次の手順を含める必要があります。 sudo apt install nginx、ただし、他にも考慮事項があります。このチュートリアルでは、作成者は次の追加手順を含めました。

アクセスを許可するようにファイアウォールを調整する
Webサーバーの確認
プロセスの管理
サーバーブロックの設定

これらの手順は、厳密には install nginx プロセスですが、Nginxを適切にインストールするために必要です。そのため、チュートリアルは基本的なドキュメントよりも価値があります。プロセスを熟考してこれらの追加のタスクを特定し、思いついたときにそれらを書き留めます。現時点では、それらを順番に用意する必要はありません。カバーするコンテンツを定義しているだけです。

これには時間がかかる場合があります。たとえば、通常はファイアウォールが適切に構成されているため、ファイアウォールをすぐに調整することを考えない場合があります。あなたがそれを考えるとき、それを書き留めてください。このステップで包括的になります。「持っていて良かった」または厳密に関連していない可能性のあるタスクについて考えてください。含めたいものをすべて考えたら、整理しましょう。

ステップ5—タスクをアウトラインに整理する

前のステップでは、チュートリアルに含めることができるタスクのリストを示したので、次のパートではそれらを整理します。操作の流れにより、これらのいくつかは明確になります。 install nginx 結果をテストする前にコマンドを実行するため、インストール手順を最初に実行する必要があります。いくつかの手順はそれほど明白ではないかもしれません：リーダーはインストール後、またはインストール前にファイアウォールを構成する必要がありますか？読者の学習目標の観点から各ステップについて考えてください。このステップは、全体的な目標に向かって進むのにどのように役立ちますか？いくつかのステップは、それらが発生する必要がある特定の場所を持っていません、そしてそれは問題ありません。

プロセスの各ステップで具体的な何かが達成されることを確認してください。つまり、各ステップには有用な動詞が含まれている必要があります。ステップとして「ファイアウォールの仕組みを理解する」と書いた場合、それは実証可能なことを達成しません。「ファイアウォールの構成」の手順では、読者に具体的なものを残します。ほとんどのトラフィックをブロックしますが、一部のトラフィックは許可するファイアウォールです。

チュートリアルの範囲外のいくつかのステップを書き留めた可能性があります。たとえば、Nginxをインストールする前にUbuntuサーバーが必要ですが、それは別のチュートリアルで説明されているため、別の手順は必要ありません。この場合、既存のチュートリアルへのリンクとともに、「Ubuntu20.04サーバーのセットアップ」を前提条件リストに追加できます。繰り返しになりますが、ステップ1で定義した学習目標を思い出し、それをステップが範囲内にあるかどうかについてのガイドにします。

他のステップは、範囲内に収まらないほど進んでいる可能性があります。 Nginxをインストールしてリバースプロキシとして使用することもできますが、そのセットアップはインストールとは別のものであり、別のチュートリアルで詳しく説明します。このチュートリアル例では、作成者はサーバーブロックの設定を推奨していますが、これは推奨事項であり、インストールの必須部分ではないことに注意してください。

各ステップに関する詳細を追加して、アウトラインを完成させます。読者が何をするのか、各ステップが重要である理由、そしてそれが次のステップとどのように関連するのかを簡単に教えてください。ファイアウォールの手順として、「リーダーはufwのNginx HTTPプロファイルを使用して、ポート80のトラフィックのみを許可します。これは、公開されているWebサーバーの標準構成です。」

ステップ6—アウトライントラップの回避

アウトラインは2つの目的を果たします。それは、執筆プロセスを容易にするフレームワークとして機能し、DigitalOcean編集チームにあなたが何について書く予定であるかを知らせ、出版のためにそれを受け入れるかどうかを決定できるようにします。受け入れられる可能性を最大限に高めるために避けることをお勧めする、アウトラインでよく見られるいくつかのことを次に示します。

背景の手順：読者が具体的なことを何もしない手順、または背景を提供するだけの手順がある場合は、その情報を記載する場所を探してください。テクノロジーが一般的に使用されているものの背景を説明したい場合は、チュートリアルの「はじめに」セクションに進んでください。読者が一歩を踏み出している理由を説明している場合は、「ジャストインタイム」の説明を使用することを検討してください。たとえば、最初にファイアウォールの背後にある理論を説明する代わりに、読者にコマンドを使用してファイアウォールを構成してもらい、次にそれらの特定のコマンドを使用した理由を正確に説明してもらいます。読者は、理論とリンクするための実践的な何かを持っていると、よりよく学ぶことができます。
説明のつかない手順： DigitalOceanの編集者はさまざまなテクノロジーについて多くの経験を持っていますが、私たちはすべての専門家ではありません。アウトラインの各ステップに説明を追加すると、目標を達成するためにステップがどのように組み合わされているかを理解するのに役立ちます。「ユーザーの設定」のような手順はそれ自体では明確ではないかもしれませんが、「データベースサービスには、セキュリティ上の理由から、特定の権限を持つ専用ユーザーが必要です。このステップでは、読者がそのユーザーを作成し、権限を設定します。」そうすれば、なぜこのステップが必要なのかがわかります。
レポジトリのクローン作成：多くのアウトラインには、チュートリアルでデプロイするサンプルプロジェクトを取得するためにレポジトリのクローンを作成するように読者に求めるステップ1があります。いくつかの理由でこのパターンを避けています。まず、チュートリアルの存続期間中、リポジトリが使用可能であることを確認する必要があります。（リポジトリが必要な場合は、DigitalOcean Communityサイトにクローンを作成し、ここでホストします。）次に、セキュリティ上の理由から、完全に説明していないコードを実行するように読者に依頼しません。第3に、チュートリアルのトピックに直接関連していない場合でも、コードのすべてのブロックを学習の機会として扱います。プロジェクトに複雑すぎてチュートリアルの邪魔をせずに説明できないCSSファイルが含まれている場合は、CSSを単純化することを検討してください。サンプルプロジェクトをチュートリアルに必要な最小限に保つことで、それが属する場所に焦点を合わせることができます。
過度に長いステップ：他の従属タスクを含むステップがある場合があります。たとえば、サーバー上の情報をシリアル化し、クライアントに送信してから、レンダリングする前に逆シリアル化する必要があるステップがあるとします。ステップが小見出しの恩恵を受けることに気付いた場合、それはステップを2つ以上の小さなステップに分割する必要があることを示しています。編集者は、この問題についてアドバイスすることができます。

結論

このチュートリアルでは、チュートリアルを定義して焦点を合わせるために必要な事前作成手順を実行しました。アイデアを洗練し、対象者と範囲を特定し、必要な手順をブレインストーミングし、概要を完成させました。これにより、執筆を開始するための強力な基盤が提供され、編集者がチュートリアルの公開を受け入れるかどうかを決定するために必要な情報も提供されます。編集者からの提案のため、または執筆中の認識のために、執筆プロセス中にアウトラインが変更されるのは正常です。アウトラインを変更できないものとは考えないでください。むしろ、軌道に乗せるためのフレームワークと考えてください。

執筆プロセスの詳細とガイダンスについては、さまざまなリソースがあります。テクニカルライティングガイドライン、テクニカル推奨事項とベストプラクティス、およびチュートリアルテンプレートを参照してください。