DigitalOceanのテクニカルライティングガイドライン

DigitalOceanは、サーバー管理とソフトウェアエンジニアリングに関連する技術記事のコレクションを構築し続けることに興奮しています。 DigitalOceanの記事の品質とスタイルに一貫性を持たせるために、次のガイドラインを作成しました。

このガイドには3つのセクションがあります。

• Style 、テクニカルチュートリアルを作成するための高レベルのアプローチ
• 構造、レイアウトとコンテンツの説明
• フォーマットと用語、マークダウンと用語のリファレンス

すぐに公開するには、記事の作成を開始する前に、StyleセクションとStructureセクション全体を読むことをお勧めします。

このガイドのFormattingセクションは、記事を書く際の参照としてMarkdownプレビューアと一緒に使用できます。

また、技術的なベストプラクティスガイドもあり、技術に焦点を当てた推奨事項の概要を説明しています。

記事の開始点として使用できるMarkdown形式の記事テンプレートを開発しました。 これらのテンプレートのいずれかを使用して、記事を計画および開発することを強くお勧めします。

私たちの記事のスタイルについて学ぶために読んでください。

---

スタイル

DigitalOceanの記事では、シカゴマニュアルオブスタイルのような特定のスタイルマニュアルは使用されていません。 代わりに、すべてのDigitalOceanチュートリアルが次のようになるように努めています。

• 包括的で、すべての経験レベル向けに書かれています
• 技術的に詳細で正しい
• 実用的で、便利で、自己完結型
• フレンドリーだがフォーマル

これらの原則は、人々が問題を解決し、開発者として成長するのに役立つ記事、チュートリアル、およびその他の学習資料を作成するように作成者をガイドします。

包括的で、すべての経験レベル向けに書かれています

私たちの記事は、読者の背景知識を前提とせずに、可能な限り明確かつ詳細に書かれています。

読者が新しいサーバーでの最初のSSH接続から最終的な動作セットアップまでに実行する必要のあるすべてのコマンドを明示的に含めます。 また、チュートリアルを理解するために必要なすべての説明と背景情報を読者に提供します。 目標は、コードやコマンドをコピーして貼り付けるだけでなく、読者が概念を学ぶことです。

「シンプル」、「ストレート」、「イージー」、「シンプル」、「明らかに」、「ジャスト」などの単語は、読者の知識を前提としているため、避けています。 著者はこれらの単語を使用して、読者がやりがいのあるトピックを推し進めるように促し、動機付けますが、多くの場合、逆の効果があります。 何かが「簡単」だと聞いた読者は、問題に遭遇したときにイライラするかもしれません。 代わりに、読者が成功するために必要な説明を提供することで、読者を励まします。

技術的に詳細で正しい

私たちの記事は技術的に正確であり、業界のベストプラクティスに従っています。 また、コードやコマンドだけでなく、詳細も提供します。 構成やプログラムコードの大きなブロックは提供しておらず、読者にテキストエディタに貼り付けてもらい、機能することを信頼しています。 読者が理解するために必要なすべての詳細を提供します。

すべてのコマンドには、必要に応じてオプションやフラグなど、詳細な説明が必要です。 コードのすべてのブロックは、それが何をするのか、そしてなぜそれがそのように機能するのかを説明する必要があります。 リーダーにコマンドの実行または構成ファイルの変更を依頼するときは、最初にそれが何をするのか、そしてなぜリーダーにそれらの変更を依頼するのかを説明してください。 これらの詳細は、読者にスキルを伸ばすために必要な背景を提供します。

作成者はチュートリアルをテストして、新しいサーバーに記述されているとおりにチュートリアルが機能することを確認します。 これにより、正確性が確保され、欠落しているステップが識別されます。 私たちの編集者はまた、読者に素晴らしい学習体験を保証するために、レビュープロセスの一部としてこれらの記事をテストします。

実用的で、便利で、自己完結型

読者がDigitalOceanの記事を読み終えたら、最初から最後まで何かをインストール、構築、またはセットアップする必要があります。 実用的なアプローチを強調します。記事の最後に、読者は使用可能な環境または構築するための例を用意する必要があります。

これが作家にとって意味することは、彼らの記事がトピックを完全にカバーするべきであるということです。 著者は、既存のDigitalOceanの記事にリンクして、読者がチュートリアルを開始する前に従う必要のある前提条件を設定し、利用可能なDigitalOceanの記事にリンクして、チュートリアルの本文に追加情報を提供する必要があります。 著者は、既存のDigitalOcean記事がなく、短い要約で情報を記事に直接追加できない場合にのみ、情報を収集するために読者をオフサイトに送る必要があります。

フレンドリーだがフォーマル

私たちのチュートリアルは、親しみやすいがフォーマルなトーンを目指しています。 これは、記事に専門用語、ミーム、過度のスラング、絵文字、またはジョークが含まれていないことを意味します。 私たちは世界中の聴衆のために書いているので、言語と文化の境界を越えて機能するトーンを目指しています。

ブログの投稿とは異なり、私たちは一人称を単数形で使用しません（例： "おもう …"）。 代わりに、2人目の人の使用をお勧めします（例： 「あなたは…を構成します」）読者と彼らが成し遂げることに焦点を合わせ続けるために。 場合によっては、一人称を複数形で使用します（例： 「インストールします…」）。

私たちは、結果に焦点を当てた動機付けの言葉を奨励します。 たとえば、「Apacheのインストール方法を学習します」の代わりに、「このチュートリアルではApacheをインストールします」を試してください。 これは読者を動機づけ、彼らが達成する必要がある目標に焦点を合わせます。

最後に、チュートリアルの言語は、多様な人間の経験を尊重し、コミュニティ行動規範に従います。 つまり、年齢、障害、民族性、性同一性または表現、経験レベル、国籍、神経多様性、外見、人種、宗教、政治的所属、性的指向に関連する（ただしこれらに限定されない）不快な言葉やその他のコンテンツを避けることを意味しますオリエンテーション、社会経済的地位、または技術の選択。

---

構造

DigitalOceanの記事は一貫した構造を持っており、これには、紹介、結論、および読者が始めるために必要な前提条件が含まれます。 ただし、具体的な構造は商品の種類によって異なります。

手順のチュートリアルでは、読者が複雑なタスクを実行する方法について説明します。 これらの記事の1つの構造は、次のようになります。

• タイトル（レベル1の見出し）
• はじめに（レベル3の見出し）
• 目標（オプション）
• 前提条件（レベル2の見出し）
• ステップ1—最初のことを行う（レベル2の見出し）
• ステップ2—次のことを行う（レベル2の見出し）
• …
• ステップn—最後のことをする（レベル2の見出し）
• 結論（レベル2の見出し）

概念的な記事には、タイトル、紹介、結論がありますが、必ずしも前提条件のセクション、目標のセクションがあるとは限らず、「ステップ」の規則に従わない場合があります。

• タイトル（レベル1の見出し）
• はじめに（レベル3の見出し）
• 前提条件（オプション）（レベル2の見出し）
• 最初のことをする（レベル2の見出し）
• 次のことをする（レベル2の見出し）
• …
• 最後のことをする（レベル2の見出し）
• 結論（レベル2の見出し）

一部の記事は、非常に小さな特定のタスクまたは解決策に焦点を当てており、多くの場合、タイトル、小さな紹介文、および最後に結論があります。 これらの記事は次のような構造になります。

• タイトル（レベル1の見出し）
• はじめに
• 前提条件（オプション）（レベル2の見出し）
• 記事の本文
• 結論の段落

記事テンプレートには、Markdownで既に記述されているこの構造があります。これらのテンプレートを、独自の記事の開始点として使用することをお勧めします。

タイトル

タイトルを書くときは、チュートリアルに従って読者が何を達成するかを慎重に考えてください。 読者がその目標を達成するために使用するツールだけでなく、チュートリアルの目標をタイトルに含めるようにしてください。

手順チュートリアルの一般的なタイトルは、次の形式に従います。 方法との上 。

たとえば、チュートリアルがCaddy Webサーバーのインストールに関するものである場合、目標はWebサイトをホストする可能性があります。 チュートリアルがFreeIPAのインストールに関するものである場合、目標は集中型Linux認証のセットアップである可能性があります。

目標を含むタイトル（「 Debian8 でCachetを使用してステータスページを作成する方法」など）は、一般に、含まないタイトル（「Cachetをインストールして設定する方法」など）よりも読者にとって有益です。 Debian 8で」）。

序章

すべての記事の最初のセクションははじめにで、通常は1〜3段落の長さです。 紹介の目的は、読者を動機付け、期待を設定し、読者が記事で何をするかを要約することです。 あなたの紹介は次の質問に答える必要があります：

• チュートリアルとは何ですか？どのソフトウェアが関係していて、各コンポーネントは（簡単に）何をしますか？
• 読者がこのトピックを学ぶ必要があるのはなぜですか？この構成でこの特定のソフトウェアを使用する利点は何ですか？ 読者がこのチュートリアルに従う必要がある実際的な理由は何ですか？
• このチュートリアルで読者は何をするか、作成しますか？サーバーをセットアップしてからテストしていますか？ 彼らはアプリを構築して展開していますか？ 具体的に説明してください。これにより、読者が必要とする動機付けが提供され、トピックに興奮するようになります。
• 読者はそれらが完了したときに何を達成しますか？彼らはどのような新しいスキルを持ちますか？ 以前はできなかったことができるでしょうか。

イントロダクションでこれらの質問に答えることは、チュートリアルの内容をイントロダクションで言及したものに合わせるため、明確で読者に焦点を合わせたチュートリアルを設計するのにも役立ちます。 良い紹介は、学習者に記事の残りの部分が何であるかを知らせることができます。

読者と彼らが何を成し遂げるかに焦点を合わせ続けてください。 「方法を学ぶ」などのフレーズを使用する代わりに、「構成する」や「構築する」などのフレーズを使用します。 これは、読者の意欲をかき立て、あなたのトピックに興奮させるのに大いに役立ちます。 さらに、テクノロジーではなく、読者が解決している問題に焦点を合わせ続けます。 たとえば、チュートリアルがReactを使用したプロジェクトの構築に関するものである場合、Reactとは何かとその歴史を説明するのではなく、プロジェクトに焦点を当てることができます。

目標

一部の大規模な手順チュートリアルでは、オプションの目標セクションを使用して、チュートリアルのコンテキスト、背景説明、および動機を最終構成の詳細から分離します。 このセクションは、チュートリアルで複数のサーバーが必要な場合、ソフトウェアスタックが大きい場合、または特に複雑な目的、方法、結果がある場合にのみ使用してください。

いくつかの良い例には、このPrometheusチュートリアルの紹介とこのPydioチュートリアルの目標が含まれます。

ほとんどのチュートリアルには、目標セクションがありません。

前提条件

DigitalOceanの記事の前提条件セクションには、非常に具体的な形式と目的があります。

目的は、読者が現在のチュートリアルに従う前に、読者が何をすべきか、または何をすべきかを正確に詳しく説明することです。 形式は、読者がチェックリストとして使用できる箇条書きです。 各箇条書きは、必要なコンテンツが存在する場合はそれをカバーする既存のDigitalOceanチュートリアルにリンクする必要があります。 これにより、最初から始めるのではなく、機能することがわかっている既存のコンテンツに依存することができます。

私たちのシステムとDevOpsチュートリアルは、バニラディストリビューションイメージの新規展開から実際のセットアップにリーダーを導くため、サーバーへの最初のSSH接続から開始するか、それを行う前提条件のチュートリアルを含める必要があります。

システム管理とDevOpsチュートリアルの一般的な前提条件は次のとおりです。

• 配布、サーバーの初期設定、および追加の必要なオプション（メモリ要件、DO APIキー、IPv6、プライベートネットワークなど）を含む、必要なサーバーの数。
• Apache、LAMPスタック、データベースなどのソフトウェアのインストールと構成。
• 必要なDNS設定またはSSL証明書。

私たちのソフトウェア開発チュートリアルも同様に機能し、開発環境の前提条件を含む、事前に必要なすべての前提条件を読者に提供します。

ソフトウェア開発チュートリアルの一般的な前提条件は次のとおりです。

• Git、Node.js、Python、Ruby、Dockerなどのローカルソフトウェアが必要です。
• GitHub、Facebook、Twitter、または読者が必要とするその他のサービスなどの追加のユーザーアカウント。
• またはHTMLプロジェクトの設定方法など、読者がプロジェクトを開始するのに役立つチュートリアル。
• DOMの理解など、読者が役立つと思われる重要な背景を提供する概念的な記事。

たとえば、Node.jsアプリケーションの構築とデプロイ、およびGitを使用したUbuntuサーバーへのデプロイに関するチュートリアルには、次の前提条件があります。

前提条件

このチュートリアルを完了するには、次のものが必要です。

• Ubuntu18.04初期サーバーセットアップガイドに従ってセットアップされた1つのUbuntu18.04サーバー。これには、ルート以外のsudo対応ユーザーとファイアウォールが含まれます。
• サーバーを指すように構成されたドメイン名。 DigitalOcean チュートリアルでホスト名を設定する方法に従って、ドメインをDigitalOceanドロップレットにポイントする方法を学ぶことができます。
• Gitがローカルマシンにインストールされています。 チュートリアルオープンソースへの貢献：Git入門に従って、コンピューターにGitをインストールしてセットアップすることができます。
• Node.jsのローカル開発環境。 Node.jsをインストールしてローカル開発環境を作成する方法に従ってください。

前提条件を読むことにより、読者は開始する前に何をする必要があるかを正確に知ることができます。 驚きはありません。

チュートリアルをテストするときは、すべての前提条件のチュートリアルを記述どおりに正確に実行して、全員が同じ開始点を使用するようにしてください。 変数を変更した場合、または前提条件の1つからオプションの手順を完了した場合は、必ず注意してください。

次のような適切な前提条件の例を見ることができます。

• Ubuntu 16.04サーバー、ソフトウェアのインストール、およびこのMinioチュートリアルの前提条件のDNSレコード。
• このNagiosおよびAlertaチュートリアルの前提条件でソフトウェアをインストールして複数のサーバーを処理する。
• UnsplashAPIを使用してReactで写真検索アプリを構築する方法を見てReactベースのWeb開発プロジェクト。

前提条件を具体的に示してください。 特定の何かへのリンクがない「JavaScriptに精通している」などの前提条件は、読者に多くのコンテキストを提供しません。 代わりに、読者が知っておくべき特定の概念をリストすることを検討し、彼らがあなたのチュートリアルを首尾よく完了することができるように彼らがスピードを上げるのを助けるリソースを彼らに提供してください。

手順

ステップセクションは、読者が行う必要があることを説明するチュートリアルの一部です。 ステップには、コマンド、コードリスト、およびファイルが含まれ、何をするかだけでなく、なぜこのようにするのかを説明する説明が提供されます。

各ステップはレベル2の見出しで始まり、動名詞を使用します。動名詞は-ingの単語です。

手順のチュートリアルでは、各ステップのタイトルを Step という単語と数字で始め、その後に全角ダッシュを付ける必要があります。

ステップ1-ユーザーアカウントの作成

タイトルの後に、読者が各ステップで何をするか、およびチュートリアルの全体的な目標を達成するために読者が果たす役割を説明する紹介文を追加します。 読者に焦点を合わせます。 「私たちは学ぶ」や「私は説明する」などのフレーズの代わりに、「あなたが構築する」や「あなたが作成する」などのフレーズを使用します。

読者が何を達成し、次にどこに向かっているのかを説明する移行文で各ステップを終了します。 これらのイントロダクションとトランジションでステップタイトルを繰り返さないでください。また、コンテキストのない命令、コマンド、または出力でステップを開始または終了しないでください。

ステップのコマンド

リーダーが実行する必要のあるすべてのコマンドは、独自のコードブロック内の独自の行にある必要があり、各コマンドの前には、コマンドの機能を説明する説明を付ける必要があります。 コマンドの後に、引数の機能やリーダーが引数を使用している理由など、コマンドに関する追加の詳細を提供する必要があります。

次のコマンドを実行して、すべての非表示ファイルを含む/home/sammyディレクトリの内容を表示します。

ls -al /home/sammy

-aスイッチは、非表示のファイルを含むすべてのファイルを表示し、-lスイッチは、タイムスタンプとファイルサイズを含む長いリストを表示します。

次の例のように、別のコードブロックを使用してコマンドとプログラムの出力を表示する必要があります。

hello.jsプログラムを実行します。

node hello.js

プログラムの出力が画面に表示されます。

OutputHello world!
This is my first Node.js program!

出力ブロックにはラベルがあり、出力を説明するテキストでコマンドから分離されていることに注意してください。 コマンドを出力から分離すると、コマンドがどこで終了し、出力がどこで開始するかが読者にとってより明確になります。

ファイルを開く、作成する、表示する

コマンドと同様に、常にその一般的な目的を説明することによってファイルまたはスクリプトを紹介し、次にリーダーがファイルに加える変更を説明します。 これらの説明がないと、読者は長期的に問題をカスタマイズ、更新、またはトラブルシューティングすることができません。

使用する各ファイルを作成または開くようにユーザーに明示的に指示します。

コマンドラインユーザーを対象としたチュートリアルでは、独自の行のコマンドを使用してファイルを作成して開くようにリーダーに指示します。

次のコマンドを使用して、ファイル/etc/hginx/configを開きます。

nano /etc/nginx/sites-available/default

すでにインストールされているため、UbuntuおよびDebianチュートリアルにはnanoエディターを使用します。 CentOSとFreeBSDのチュートリアルではviを使用しています。 いずれの場合も、touchを使用して新しい空のファイルを作成することは避けてください。リーダーは、代わりにエディターを使用してファイルを直接作成できます。

フロントエンド開発チュートリアルなど、リーダーがコマンドラインインターフェイスを使用することが期待されていないチュートリアルの場合は、コマンドを省略してファイルを開くことができます。 ただし、どのファイルを明示的に開くかをリーダーに必ず伝えてください。

エディターでファイルsrc/App.jsを開きます。

読者は、どのファイルを使用しているかを常に知っている必要があります。

コードブロック

読者にコードを書くように依頼する場合は、コマンドについても同じアプローチに従います。コードブロックに、その機能の高レベルの説明を導入します。 次に、コードを表示してから、重要な詳細を呼び出します。

次に例を示します。

テキストエディタでファイルhello.jsを作成します。

nano hello.js

画面にメッセージを出力するファイルに次のコードを追加します。

hello.js

console.log("Hello world!");
console.log("this is my first Node.js program!")

console.log関数は文字列を受け取り、それを独自の行で画面に出力します。

コードリストには、ファイル名を明確に示すラベルが付いていることに注意してください。

時々、ファイルを開いて、読者に特定の何かを変更するように頼むでしょう。 これを行うときは、ファイルの関連部分を表示し、強調表示を使用して、何を変更する必要があるかを明確にします。

エディターでファイル/etc/nginx/sites-available/defaultを開きます。

nano /etc/nginx/sites-available/default

server_nameの値をドメイン名に変更します。

/ etc / nginx / sites-available / default

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;

    root /usr/share/nginx/html;
    index index.html index.htm;

    server_name your_domain;
...

}

DigitalOceanのカスタムマークダウンおよびフォーマットガイドラインは、チュートリアルの説明をできるだけ読みやすくするために設計されています。 このDockerSwarmチュートリアルは、カスタムMarkdownを使用して、ローカルだけでなく複数の異なるサーバーで実行されるコマンドを区別する方法の良い例です。

結論

チュートリアルの結論は、読者がチュートリアルに従って達成したことを要約する必要があります。 「方法を学んだ」などのフレーズを使用する代わりに、「構成した」や「構築した」などのフレーズを使用します。

結論は、読者が次に何ができるかについても説明する必要があります。 これには、読者が探索できるユースケースまたは機能の説明、追加のセットアップまたは構成を含む他のDigitalOceanチュートリアルへのリンク、および外部ドキュメントを含めることができます。

いくつかの良い例には、このLXDチュートリアルの結論、このCPU監視チュートリアルの結論、およびこのMosquittoチュートリアルの結論が含まれます。

---

フォーマット

DigitalOceanチュートリアルは、Markdownマークアップ言語でフォーマットされています。 Daring Fireball は、慣れていない場合に包括的なMarkdownガイドを公開しています。 DigitalOceanは、いくつかのカスタムMarkdownも使用します。 カスタムマークダウンの例は、以下の該当するセクションにあります。

ヘッダー

チュートリアルの各セクションには、対応するヘッダーがあります。タイトルはH1ヘッダーである必要があります。 イントロダクションはH3ヘッダーである必要があります。 目標、前提条件、手順、および結論には、H2ヘッダーが必要です。 この形式は、Markdown記事テンプレートで確認できます。

手順チュートリアルの場合、ステップヘッダーには、ステップ番号（数字）の後にemダッシュ（〜）を含める必要があります。

ステップヘッダーも動名詞を使用する必要があります。動名詞は-ingワードです。 ステップヘッダーの例は、ステップ1 —Nginxのインストールです。

H3ヘッダーは慎重に使用し、H4ヘッダーは避けてください。 サブヘッダーを使用する必要がある場合は、チュートリアルのそのセクション内にそのレベルのヘッダーが2つ以上あることを確認してください。 または、代わりに複数の手順を実行することを検討してください。

行レベルのフォーマット

太字のテキストは次の目的で使用する必要があります。

• 目に見えるGUIテキスト
• wordpress-1やsammyなどのホスト名とユーザー名
• 用語リスト
• 新しいサーバーやユーザーへの切り替えなど、コマンドのコンテキストを変更するときに強調する

斜体は、専門用語を導入する場合にのみ使用してください。 たとえば、Nginxサーバーはロードバランサーになります。

インラインコードフォーマットは、次の目的で使用する必要があります。

• unzipなどのコマンド名
• mysql-serverなどのパッケージ名
• オプションのコマンド
• ~/.ssh/authorized_keysなどのファイル名とパス
• http://your_domainなどのURLの例
• :3000などのポート
• ENTERやCTRL+Cのように、キーを同時に押す必要がある場合は、すべて大文字でプラス記号+を使用する必要があります。

コードブロック

コードブロックは次の目的で使用する必要があります。

• チュートリアルを完了するためにリーダーが実行する必要のあるコマンド
• ファイルとスクリプト
• 端子出力
• テキストであるインタラクティブな対話

省略記号を使用してファイルの抜粋と省略を示します（ 。 。 。 ）：

/ etc / nginx / sites-available / default

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;

    root /usr/share/nginx/html;
    index index.html index.htm;

    server_name your_domain;
...

}

ほとんどのファイルをデフォルト設定のままにしておくことができる場合は、通常、変更が必要なセクションのみを表示することをお勧めします。

コードブロックプレフィックス

コマンドプロンプト（$または#）をコードブロックに含めないでください。 代わりに、root以外のユーザーコマンド、rootユーザーコマンド、およびカスタムプレフィックスにそれぞれDigitalOceanのカスタムマークダウンを使用します。

```command
sudo apt-get update
```

```super_user
adduser sammy
```

```custom_prefix(mysql>)
FLUSH PRIVILEGES;
```

これは、レンダリングされたときの前述の例の外観です。

sudo apt-get update

adduser sammy

FLUSH PRIVILEGES;

この方法でコマンドを提示すると、読者が誤ってプロンプト文字を選択することはありません。

コードブロックラベル

DigitalOceanのMarkdownには、ラベルとセカンダリラベルも含まれています。 ブロック内の任意の場所に[label Label text]または[secondary_label Secondary label text]の行を追加することで、コードブロックにラベルを追加できます。

ラベルを使用して、ファイルの内容を含むコードブロックをファイル名でマークします。 たとえば、app.jsというファイルがある場合は、[label app.js]を使用してコードブロックにラベルを付けます。

```js
[label app.js]
console.log("Hello World!");
```

ラベルはコードリストの上に表示されます。

app.js

console.log("Hello World!");

次のように、セカンダリラベルを使用して、画面に印刷された端末またはプログラムの出力をマークします。

```
[secondary_label Output]
Hello World!
```

二次ラベルは次のようになります。

OutputHello World!

ラベルは、読者が見ているものと、それが全体像にどのように適合するかを理解するのに役立ちます。

コードブロック環境の色

ローカルマシンや複数のサーバーなど、複数のコンピューターでリーダーを動作させる場合があります。 出力に異なる色を使用すると、読者がこれを理解しやすくなります。 DigitalOceanのMarkdownを使用すると、ブロック内の任意の場所に[environment name]の行を追加して、コードブロックの背景に色を付けることができます。 nameのオプションは、local、second、third、fourth、およびfifthです。

たとえば、チュートリアルを作成していて、サーバーではなくローカルで実行する必要があるコマンドを表示する場合は、[environment local]を使用できます。

ssh root@your_server_ip

これらは非プライマリサーバーコマンドの例であり、マルチサーバーのセットアップに役立ちます。

[environment second]の使用は、次のようになります。

echo "Secondary server"

[environment third]の使用は、次のようになります。

echo "Third server"

[environment fourth]の使用は、次のようになります。

echo "Fourth server"

そして、[environment fifth]は次のようになります。

echo "Fifth server

マルチサーバーまたはマルチ環境のチュートリアルでこれらの色を使用します。

注意と警告

DigitalOcean Markdownパーサーを使用すると、カスタムのnoteおよびwarningコードブロックを使用して非常に重要なテキストを表示できます。

これがメモと警告のマークダウンの例です（これは画像です）：

レンダリングされた結果は次のとおりです。

注：これは注です。

警告：これは警告です。

DigitalOcean固有の情報

[info]コールアウトは、DigitalOcean固有の機能について説明するときに役立ちます。

この機能は、DigitalOceanのドロップレットに固有のものです。

変数

設定ファイルのURLの例や変更された行など、リーダーが変更する必要のある項目を強調表示します。 あなたは私たちの習慣で単語や行を囲むことによってこれを行うことができます <^> マークダウン。

注：1組の記号で複数の行を強調表示することはできないため、各行を個別に強調表示する必要があります。

通常はin-line codeフォーマットも使用するコンテキストで変数を参照する場合は、both stylesを使用する必要があります。 「上記の赤で強調表示」ではなく「前のコードブロックで強調表示」などの言語を使用して、チュートリアルにできるだけアクセスできるようにしてください。

ハイライトの色が変わる可能性があるため、「黄色でハイライトされた」などの言葉は避けてください。

画像およびその他のアセット

画像は、ポイントをすばやく説明したり、ステップで追加の説明を提供したりできます。 GUIのスクリーンショット、対話型ダイアログ、およびサーバー設定の図に画像を使用します。 コードのスクリーンショット、構成ファイル、出力、またはコピーして記事に貼り付けることができるものに画像を使用しないでください。

チュートリアルに画像を含める場合は、次のガイドラインに従ってください。

• スクリーンリーダーを使用している読者が画像ではなく代替テキストに依存できるように、説明的な代替テキストを含めます。
• .pngファイル形式を使用してください。
• imgurで画像をホストします。
• 高さをできるだけ短くして画像を作成します。

チュートリアル用の図のモックアップを作成すると、DigitalOceanスタイルの図が作成されます。 また、公開時にすべての画像をDigitalOceanサーバーにアップロードします。

チュートリアルに画像を含めるためのMarkdownの例を次に示します。

![Alt text for screen readers](http://imgur.com/your_image_url)

場合によっては、チュートリアルの本文に表示するには長すぎる構成ファイルにリーダーがアクセスできるようにする必要があります。 DigitalOceanは、このファイルをアセットサーバーでホストします。 標準のリンク形式を使用して、ファイルにリンクできます。

用語

技術記事とチュートリアルでは多くの用語が使用され、いくつかの用語と単語の使用法が標準化されています。

ユーザー、ホスト名、およびドメイン

デフォルトのユーザー名の例はsammyです。 webdav-kaiやnsdなど、役立つ説明的なものを選択することもできます。

your_server がデフォルトのホスト名ですが、 django_replica_1 など、マルチサーバー設定でよりわかりやすいものを選択することもできます。

your_domainがデフォルトのドメインです。 マルチサーバー設定の場合、primary-1.your_domainまたはreplica-1.your_domainのようなものを選択できます。 example.com はドキュメントの有効なドメインですが、チュートリアルで your_domain を使用すると、読者が例でドメインを変更する必要があることがより明確になります。

次のように、構成ファイル、コード、および出力ブロックでこれらを使用する場合は、強調表示を使用します。

設定ファイルの例

ip: your_server_ip
domain: primary-1.your_domain

これにより、読者は変更すべきことがあることが明確になります。

IPアドレスとURL

your_server_ipは、インラインコードのフォーマットと変数の強調表示を備えており、IPアドレスを表示するデフォルトの方法です。 primary_private_ipやreplica_private_ipのような名前の複数のIPアドレスを表示できます。 より現実的なIPアドレスを説明する必要がある場合は、RFC-5737 に従って、ドキュメント用に予約されている2つのブロックのうちののアドレスを使用してください。 具体的には、パブリックアドレスなどの203.0.113.0/24と、プライベートアドレスなどの198.51.100.0/24をお勧めします。

リーダーがカスタマイズする必要のある変数を含むURLの例では、変数を強調表示したコードフォーマットを使用する必要があります。 デフォルトではyour_domainを使用します。 https://your_domain:3000/simple/やhttp://your_server_ip/のように。 ただし、ライブリンクは、代わりに、追加のフォーマットなしで標準のMarkdownリンクスタイルを使用する必要があります。

ソフトウェア

彼らのソフトウェアの名前の公式ウェブサイトの大文字を使用してください。 製品のWebサイトが大文字と小文字を区別しない場合は、1つの記事内で一貫してください。

ソフトウェアについて最初に言及するときに、ソフトウェアのホームページにリンクします。

マルチサーバーのセットアップ

技術的な明確さのために、マルチサーバー設定にはプロジェクトの用語を使用してください。 条件がプロジェクトから来ていることを明確にしてください。 例：「Djangoプロジェクトは、元のサーバーをプライマリと呼び、セカンダリサーバーをレプリカと呼びます。 MySQLプロジェクトでは、元のサーバーをマスターと呼び、セカンダリサーバーをスレーブと呼びます。」

マルチサーバーアーキテクチャについてより抽象的に説明する場合は、プライマリとレプリカまたはマネージャーとワーカーという用語を使用してください。

技術的なベストプラクティス

技術的なベストプラクティスガイドガイドには、読者に役立つ一貫性のある高品質のチュートリアルを作成するのに役立つガイダンスが含まれています。

このリンクをたどると、はDigitalOceanの作者になります。