ArticlesDigitalOceanは、サーバー管理およびソフトウェアエンジニアリングに関連する技術記事のコレクションを作成し続けることに興奮しています。DigitalOceanの記事に一貫した品質とスタイルを持たせるために、次のガイドラインを作成しました。このガイドには3つのセクションがあります。*、マークダウンと用語のリファレンスすばやく公開するには、DigitalOceanコミュニティの作成者はスタイルと構造のセクション全体を読む必要があります。previewer]は、書き込み中に参照として使用できます。[技術的なベストプラクティスガイド]も用意しています。‘スタイルDigitalOceanの記事は次のとおりです。すべての経験レベルのための包括的で書かれた私たちの記事は、読者の背景知識を仮定することなく、できるだけ明確かつ詳細に書かれています。読者が新しいサーバー上の最初のSSH接続から最終的な作業セットアップに移動するために必要なすべてのコマンドを明示的に含めます。チュートリアルを理解するために必要なすべての説明と背景情報を読者に提供します。目標は、読者がコピーして貼り付けるだけでなく、学ぶことです。技術的に詳細かつ正しいすべてのチュートリアルは、新しいサーバーでテストされ、最初から機能することを確認します。すべてのコマンドには、必要に応じてオプションとフラグを含む詳細な説明が必要です。読者にコマンドを実行するか、構成ファイルを変更するように依頼する場合、最初にコマンドの実行内容または変更を行う理由を説明してください。読者がDigitalOceanの記事を終えたら、最初から最後まで何かをインストールまたはセットアップする必要があります。実用的なアプローチを強調します。記事の最後で、読者に使用可能な環境または構築する例を残しておく必要があります。作家にとってこれが意味することは、彼らの記事がトピックを徹底的にカバーし、必要な場合、前提条件を設定するために別のDigitalOceanの記事にリンクすることです。著者は、記事に簡単に追加できる情報を収集するために、読者をサイト外に送るべきではありません。フレンドリーだがフォーマル私たちのチュートリアルは、友好的だが正式な口調を目指しています。これは、記事に専門用語、ミーム、または過度のジョークが含まれていないことを意味します。「構成します...」)。構造DigitalOceanチュートリアルは、次のセクションで構成される一貫した構造を持っています。[記事テンプレート]には、Markdownにこのレイアウトがあり、自分の記事の出発点として使用できます。[このガイドの書式設定セクション]には、書式設定規則の詳細が記載されています。タイトル典型的なタイトルは、次の形式に従います。タイトルを書くときは、チュートリアルに従って読者が何を達成するかについて慎重に考えてください。読者がその目標を達成するために使用するツールだけでなく、チュートリアルの目標をタイトルに含めるようにしてください。[ウェブサイトをホスト]。[集中Linux認証を設定します]。8でCachetをインストールおよび設定する方法」など)。はじめにと目標すべてのチュートリアルの最初のセクションは*はじめに*で、通常は1〜3段落です。+紹介の目的は、読者のために次の質問に答えることです。読者がこのチュートリアルに従うべき実用的な理由は何ですか?一部のチュートリアルでは、オプションの*目標*セクションを使用して、チュートリアルのコンテキスト、背景説明、動機を最終構成の詳細から分離しています。チュートリアルで複数のサーバーが必要な場合、大規模なソフトウェアスタックがある場合、または特に複雑な目的、方法、結果がある場合にのみ、このセクションを使用してください。[このPrometheusチュートリアルの紹介]とhttps://www.digitaloceanがあります。[このPydioチュートリアルの目標]。前提条件DigitalOceanチュートリアルの*前提条件*セクションには、非常に具体的な形式と目的があります。目的は、読者が現在のチュートリアルを実行する前に、読者が何をすべきか、または何をすべきかを正確に説明することです。この形式は、読者がチェックリストとして使用できる箇条書きリストです。各箇条書きは、必要なコンテンツをカバーする既存のDigitalOceanチュートリアルにリンクする必要があります。これにより、ゼロから始めるのではなく、動作することがわかっている既存のコンテンツに依存できます。一般的な前提条件の箇条書きには、次のものがあります。APIキー、IPv6、プライベートネットワークなど)を含む、必要なサーバーの数。ソフトウェアのインストールと構成。必要なDNS設定またはSSL証明書。GitHub、Facebook、Twitter、または読者が必要とする他のサービスなどの追加のユーザーアカウント。チュートリアルをテストするときは、すべての前提条件チュートリアルに記載されているとおりに実行し、全員が同じ開始点を使用するようにしてください。変数を変更した場合、または前提条件のいずれかからオプションの手順を完了した場合は、必ず注意してください。システム管理チュートリアルでは、読者にバニラディストリビューションイメージの新規展開から実際のセットアップを紹介します。したがって、サーバーへの最初のSSH接続から開始するか、それを行う前提条件チュートリアルを含める必要があります。以下の前提条件の例を確認できます。[このMinioチュートリアルの前提条件]。7サーバーとDNSレコード前提条件]。[このCachetチュートリアルの前提条件]。[このNagiosおよびAlertaチュートリアルの前提条件]でソフトウェアをインストールして複数のサーバーを処理する。ステップ*ステップ*セクションは、読者が何をする必要があるかを説明するチュートリアルの一部です。各ステップは、チュートリアルの全体的な目標を達成するためにステップがカバーするものとその役割を説明する紹介文で始まります。各ステップの最後に、読者が達成したことと次に進む場所を説明する移行文を付けます。これらの導入部と移行部でステップのタイトルを繰り返さないようにし、コンテキストのない指示、コマンド、または出力でステップを開始または終了しないでください。ステップ内のすべてのコマンドは、独自のコードブロック内の独自の行にある必要があり、各コマンドの前に説明が必要です。同様に、常にファイルまたはスクリプトの一般的な目的を説明して紹介し、読者がファイルに加える変更を説明します。これらの説明がないと、読者は長期的にサーバーをカスタマイズ、更新、またはトラブルシューティングすることができません。[カスタムマークダウンとフォーマットのガイドライン]は、チュートリアルの手順をできるだけ読みやすくするために設計されています。Swarmチュートリアル]は、カスタムMarkdownを使用して、複数の異なるサーバーで実行されるコマンドとローカルで実行されるコマンドを区別する方法の良い例です。結論*結論*は、読者がチュートリアルに従って達成したことを要約する必要があります。読者が次にできることも説明する必要があります。これには、読者が探索できるユースケースまたは機能の説明、追加のセットアップまたは構成を含む他のDigitalOceanチュートリアルへのリンク、および外部ドキュメントを含めることができます。[このMosquittoチュートリアルの結論]。‘フォーマットDigitalOceanチュートリアルは、Markdownマークアップ言語でフォーマットされています。Fireballは、慣れていない場合に包括的なマークダウンガイドを公開しています。Markdown]も使用します。カスタムマークダウンの例は、以下の適切なセクションにあります。ヘッダチュートリアルの各セクションには対応するヘッダーがあります。タイトルはH1ヘッダーである必要があります。結論にはH2ヘッダーが必要です。templates]で確認できます。手続き型チュートリアルの場合、ステップヘッダーには、ステップ番号(数字)に続いてemダッシュ(–)を含める必要があります。ステップヘッダーは動名詞を使用する必要があります。*のインストールです。H3ヘッダーは控えめに使用し、H4ヘッダーは避けてください。サブヘッダーを使用する必要がある場合は、チュートリアルのそのセクション内にそのレベルのヘッダーが2つ以上あることを確認してください。代わりに複数のステップを作成することを検討してください。行レベルの書式設定*太字*は以下に使用する必要があります。用語リスト新しいサーバーまたはユーザーへの切り替えなど、コマンドのコンテキストを変更する際の強調_Italics_は、技術用語を紹介する場合にのみ使用してください。Nginxサーバーは_ロードバランサー_になります。インラインコードの書式設定は、次の目的で使用する必要があります。*を使用する必要があるキーを押しますコードブロックコードブロックを使用する必要があります。チュートリアルを完了するために読者が実行する必要があるコマンドファイルとスクリプトターミナル出力テキスト形式のインタラクティブな対話ファイルの抜粋と省略は、省略記号(...)で示すことができます。ほとんどのファイルをデフォルト設定のままにしておくことができる場合は、通常、変更する必要があるセクションのみを表示することをお勧めします。コードブロックプレフィックスコードブロックにコマンドプロンプトを含めないでください。代わりに、非ルートユーザーコマンド、ルートユーザーコマンド、カスタムプレフィックスにそれぞれDigitalOceanのカスタムマークダウンを使用します。PRIVILEGES;```これは、レンダリング時の上記の例の外観です。_コードブロックラベルDigitalOceanのMarkdownには、ラベルとセカンダリラベルも含まれます。+`を追加して、コードブロックにラベルを追加できます。ラベルを使用して、ファイルの内容を含むコードブロックをファイル名でマークします。2次ラベルを使用して、端末出力をマークします。表示されるラベルは次のようになります。」の行を追加することで、コードブロックの背景に色を付けることができます。これはローカルサーバーコマンドの例です。protected]これらは非プライマリサーバーコマンドの例で、マルチサーバーのセットアップに役立ちます。*コードブロックを使用できます。以下は、メモと警告のマークダウンの例です(これは画像です)。[注意と警告]レンダリング結果は次のとおりです。変数URLの例や構成ファイルの変更された行など、リーダーが変更する必要がある項目を強調表示します。*マークダウンで単語または行を囲みます。1組のシンボルで複数の行を強調表示できないため、各行を個別に強調表示する必要があることに注意してください。通常、インラインコード+フォーマットも使用するコンテキストで変数を参照する場合は、+を使用する必要があります。「上記の赤で強調表示」ではなく、「前のコードブロックで強調表示」などの言語を使用して、チュートリアルにできるだけアクセスできるようにします。画像は、ポイントをすばやく説明したり、ステップで追加の説明を提供したりできます。GUIのスクリーンショット、対話型ダイアログ、およびサーバー設定の図に画像を使用します。コードのスクリーンショット、設定ファイル、出力、または記事にコピーして貼り付けることができるものには画像を使用しないでください。チュートリアルに画像を含める場合は、次のガイドラインに従ってください。スクリーンリーダーを使用する読者が画像ではなく代替テキストに依存できるように、説明的な代替テキストを含めます。+`ファイル形式を使用するimgurのホストイメージ可能な限り短い高さで画像を作成するチュートリアル用のダイアグラムのモックアップを作成する場合、DigitalOceanスタイルのダイアグラムを作成します。公開時にすべての画像をDigitalOceanサーバーにアップロードします。チュートリアルに画像を含めるためのMarkdownの例を次に示します。readers](http://imgur.com/your_image_url)場合によっては、読者がチュートリアルの本文に表示するには長すぎる構成ファイルにアクセスできるようにする必要があります。DigitalOceanは、このファイルをアセットサーバーでホストします。標準のリンク形式を使用して、ファイルにリンクできます。*など、わかりやすい説明的なものを選択することもできます。*のようなマルチサーバー設定では、わかりやすい名前を選択することをお勧めします。デフォルトのドメインです。ようなものを選択できます。*を使用すると、読者が例でドメインを変更する必要があることがより明確になります。次のように、構成ファイルでこれらを使用する場合、強調表示を使用します。primary-1.これにより、読者に変更すべき点があることが明確になります。IPアドレスとURLIPアドレスを表示するデフォルトの方法は、インラインコードの書式設定と変数の強調表示を備えた「」です。「」や「+」などの名前の複数のIPアドレスを表示できます。[RFC-5737に準拠したドキュメント用に予約されている2つのブロックの1つ]のアドレスを使用します。リーダーがカスタマイズする必要のある変数を含むURLの例では、変数が強調表示されたコード形式を使用する必要があります。