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

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

  • * https://www.digitalocean.com/community/tutorials/digitalocean-s-writing-guidelines#style [Style] *、テクニカルチュートリアルを作成するための高度なアプローチ

  • * https://www.digitalocean.com/community/tutorials/digitalocean-s-writing-guidelines#structure [Structure] *、レイアウトとコンテンツの説明

  • * https://www.digitalocean.com/community/tutorials/digitalocean-s-writing-guidelines#formatting [Formatting]およびhttps://digitalocean.com/community/tutorials/digitalocean-s-writing-guidelines#terminology [用語] *、マークダウンと用語のリファレンス

すばやく公開するには、DigitalOceanコミュニティの作成者はスタイルと構造のセクション全体を読む必要があります。 templatesは記事の出発点として有用であり、このガイドのフォーマットセクションとhttps://www.digitalocean.com / community / markdown [Markdown previewer]は、書き込み中に参照として使用できます。 また、技術重視の推奨事項については、https://www.digitalocean.com/community/tutorials/technical-recommendations-and-best-practices-for-digitalocean-s-tutorials [技術的なベストプラクティスガイド]も用意しています。

” ” ‘

スタイル

DigitalOceanの記事は次のとおりです。

  • すべての経験レベルのための包括的で書かれた

私たちの記事は、読者の背景知識を仮定することなく、できるだけ明確かつ詳細に書かれています。

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

  • 技術的に詳細かつ正しい

すべてのチュートリアルは、新しいサーバーでテストされ、最初から機能することを確認します。 すべてのコマンドには、必要に応じてオプションとフラグを含む詳細な説明が必要です。 読者にコマンドを実行するか、構成ファイルを変更するように依頼する場合、最初にコマンドの実行内容または変更を行う理由を説明してください。

  • 実用的で便利な自己完結型

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

作家にとってこれが意味することは、彼らの記事がトピックを徹底的にカバーし、必要な場合、前提条件を設定するために別のDigitalOceanの記事にリンクすることです。 著者は、記事に簡単に追加できる情報を収集するために、読者をサイト外に送るべきではありません。

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

私たちのチュートリアルは、友好的だが正式な口調を目指しています。 これは、記事に専門用語、ミーム、または過度のジョークが含まれていないことを意味します。 これは、ブログの投稿とは異なり、一人称を使用しないことを意味します(例: “おもう …”)。 代わりに、一人称を複数使用します(例: 「…をインストールします」または2人目(例: 「構成します…」)。

” ” ‘

構造

DigitalOceanチュートリアルは、次のセクションで構成される一貫した構造を持っています。

  • タイトル

  • 前書き

  • 目標(オプション)

  • 前提条件

  • ステップ1-最初のことを行う

  • ステップ2-次のことを行う

  • ステップn-最後のことをする

  • 結論

https://github.com/do-community/do-article-templates [記事テンプレート]には、Markdownにこのレイアウトがあり、自分の記事の出発点として使用できます。 http://do.co/style#formatting [このガイドの書式設定セクション]には、書式設定規則の詳細が記載されています。

タイトル

典型的なタイトルは、次の形式に従います。* How To <Accomplish a Task> with <Software> on <Distro> *。

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

たとえば、Caddyのインストールに関するチュートリアルの場合、目標はhttps://www.digitalocean.com/community/tutorials/how-to-host-a-website-with-caddy-on-ubuntu-16- 04 [ウェブサイトをホスト]。 FreeIPAのインストールに関するチュートリアルの場合、目標はhttps://www.digitalocean.com/community/tutorials/how-to-set-up-centralized-linux-authentication-with-freeipa-on-centos-7 [集中Linux認証を設定します]。 目標を含むタイトル(「https://www.digitalocean.com/community/tutorials/how-to-create-a-status-page-with-cachet-on-debian-8 [ステータスページの作成方法Debian 8でCachetを使用]])は一般的に、そうでないタイトルよりも読者にとって有益です(「Debian 8でCachetをインストールおよび設定する方法」など)。

はじめにと目標

すべてのチュートリアルの最初のセクションは*はじめに*で、通常は1〜3段落です。 +紹介の目的は、読者のために次の質問に答えることです。

  • チュートリアルの目標は何ですか? 彼らがそれに従うならば、読者は何を達成しますか?

  • どのソフトウェアが関与しており、各コンポーネントは何をしますか(簡単に)?

  • この構成でこの特定のソフトウェアを使用する利点は何ですか? 読者がこのチュートリアルに従うべき実用的な理由は何ですか?

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

良い例として、https://www.digitalocean.com/community/tutorials/how-to-install-prometheus-on-ubuntu-16-04#introduction [このPrometheusチュートリアルの紹介]とhttps://www.digitaloceanがあります。 com / community / tutorials / how-to-host-a-file-sharing-server-with-pydio-on-ubuntu-14-04#goals [このPydioチュートリアルの目標]。

前提条件

DigitalOceanチュートリアルの*前提条件*セクションには、非常に具体的な形式と目的があります。

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

一般的な前提条件の箇条書きには、次のものがあります。

  • 配布、サーバーの初期セットアップ、およびその他の必要なオプション(メモリ要件、DO APIキー、IPv6、プライベートネットワークなど)を含む、必要なサーバーの数。

  • ソフトウェアのインストールと構成。

  • 必要なDNS設定またはSSL証明書。

  • GitHub、Facebook、Twitter、または読者が必要とする他のサービスなどの追加のユーザーアカウント。

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

システム管理チュートリアルでは、読者にバニラディストリビューションイメージの新規展開から実際のセットアップを紹介します。したがって、サーバーへの最初のSSH接続から開始するか、それを行う前提条件チュートリアルを含める必要があります。

以下の前提条件の例を確認できます。

ステップ

*ステップ*セクションは、読者が何をする必要があるかを説明するチュートリアルの一部です。

各ステップは、チュートリアルの全体的な目標を達成するためにステップがカバーするものとその役割を説明する紹介文で始まります。 各ステップの最後に、読者が達成したことと次に進む場所を説明する移行文を付けます。 これらの導入部と移行部でステップのタイトルを繰り返さないようにし、コンテキストのない指示、コマンド、または出力でステップを開始または終了しないでください。

ステップ内のすべてのコマンドは、独自のコードブロック内の独自の行にある必要があり、各コマンドの前に説明が必要です。 同様に、常にファイルまたはスクリプトの一般的な目的を説明して紹介し、読者がファイルに加える変更を説明します。 これらの説明がないと、読者は長期的にサーバーをカスタマイズ、更新、またはトラブルシューティングすることができません。

DigitalOceanのhttp://do.co/style#formatting [カスタムマークダウンとフォーマットのガイドライン]は、チュートリアルの手順をできるだけ読みやすくするために設計されています。 https://www.digitalocean.com/community/tutorials/how-to-create-a-cluster-of-docker-containers-with-docker-swarm-and-digitalocean-on-ubuntu-16-04 [このDocker Swarmチュートリアル]は、カスタムMarkdownを使用して、複数の異なるサーバーで実行されるコマンドとローカルで実行されるコマンドを区別する方法の良い例です。

結論

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

良い例には、https://www.digitalocean.com/community/tutorials/how-to-set-up-and-use-lxd-on-ubuntu-16-04#conclusion [このLXDチュートリアルの結論]、https: //www.digitalocean.com/community/tutorials/how-to-monitor-cpu-use-on-digitalocean-droplets#conclusion [このCPU監視チュートリアルの結論]およびhttps://www.digitalocean.com/community/ tutorials / how-to-install-and-secure-the-mosquitto-mqtt-messaging-broker-on-ubuntu-16-04#conclusion [このMosquittoチュートリアルの結論]。

” ” ‘

フォーマット

DigitalOceanチュートリアルは、Markdownマークアップ言語でフォーマットされています。 Daring Fireballは、慣れていない場合に包括的なマークダウンガイドを公開しています。 DigitalOceanでは、https://www.digitalocean.com/community/markdown [custom Markdown]も使用します。 カスタムマークダウンの例は、以下の適切なセクションにあります。

ヘッダ

チュートリアルの各セクションには対応するヘッダーがあります。タイトルはH1ヘッダーである必要があります。導入部はH3ヘッダーである必要があります。目標、前提条件、手順、および結論にはH2ヘッダーが必要です。 この形式は、https://github.com/do-community/do-article-templates [Markdown article templates]で確認できます。

手続き型チュートリアルの場合、ステップヘッダーには、ステップ番号(数字)に続いてemダッシュ()を含める必要があります。 また、ステップヘッダーは動名詞を使用する必要があります。これは* -ing *語です。 ステップヘッダーの例は、*ステップ1-Nginx *のインストールです。

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

行レベルの書式設定

*太字*は以下に使用する必要があります。

  • 表示されるGUIテキスト

  • * wordpress-1 sammy *などのホスト名とユーザー名

  • 用語リスト

  • 新しいサーバーまたはユーザーへの切り替えなど、コマンドのコンテキストを変更する際の強調

_Italics_は、技術用語を紹介する場合にのみ使用してください。 たとえば、Nginxサーバーは_ロードバランサー_になります。

インラインコードの書式設定は、次の目的で使用する必要があります。

  • `+ unzip +`のようなコマンド名

  • `+ mysql-server`のようなパッケージ名

  • オプションのコマンド

  • `+〜/ .ssh / authorized_keys`のようなファイル名とパス

  • `+ http:// +`のようなURLの例

  • `+:3000 +`のようなポート

  • 「+ ENTER 」や「 CTRL + C +」のようにキーを同時に押す必要がある場合は、すべて大文字で入力し、プラス記号* + *を使用する必要があるキーを押します

コードブロック

コードブロックを使用する必要があります。

  • チュートリアルを完了するために読者が実行する必要があるコマンド

  • ファイルとスクリプト

  • ターミナル出力

  • テキスト形式のインタラクティブな対話

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

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

コードブロックにコマンドプロンプトを含めないでください。 代わりに、非ルートユーザーコマンド、ルートユーザーコマンド、カスタムプレフィックスにそれぞれDigitalOceanのカスタムマークダウンを使用します。

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

```super_user
adduser
```

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

これは、レンダリング時の上記の例の外観です。

_ _

sudo apt-get update
adduser sammy
FLUSH PRIVILEGES;

_ _

コードブロックラベル

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

ラベルを使用して、ファイルの内容を含むコードブロックをファイル名でマークします。 2次ラベルを使用して、端末出力をマークします。

表示されるラベルは次のようになります。

これはラベルのテキストです

This is one line of the file
This is another line of the file
. . .
This is a line further down the file

二次ラベルの例:

This is the secondary label textThis is some output from a command
コードブロック環境の色

DigitalOceanのマークダウンを使用すると、ブロック内のどこかに「+ [environment] 」の行を追加することで、コードブロックの背景に色を付けることができます。 「+」のオプションは、「+ local 」、「 second」、「+ third」、「+ fourth」、および「+ fifth」です。

これはローカルサーバーコマンドの例です。

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

echo "Secondary server"
echo "Third server"
echo "Fourth server"
echo "Fifth server

注意と警告

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

以下は、メモと警告のマークダウンの例です(これは画像です)。

image:https://assets.digitalocean.com/articles/do_formatting/note_warning.png [注意と警告]

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

変数

URLの例や構成ファイルの変更された行など、リーダーが変更する必要がある項目を強調表示します。 これを行うには、カスタム* <^> *マークダウンで単語または行を囲みます。 1組のシンボルで複数の行を強調表示できないため、各行を個別に強調表示する必要があることに注意してください。

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

「下の赤で強調表示された」などの言葉は避けてください

画像とその他の資産

画像は、ポイントをすばやく説明したり、ステップで追加の説明を提供したりできます。 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:
domain: primary-1.

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

IPアドレスとURL

IPアドレスを表示するデフォルトの方法は、インラインコードの書式設定と変数の強調表示を備えた「」です。 「」や「+」などの名前の複数のIPアドレスを表示できます。 より現実的なIPアドレスを説明する必要がある場合は、https://tools.ietf.org/html/rfc5737 [RFC-5737に準拠したドキュメント用に予約されている2つのブロックの1つ]のアドレスを使用します。 具体的には、たとえばパブリックアドレスには「 203.0.113.0 / 24 」、プライベートアドレスには「 198.51.100.0 / 24 +」をお勧めします。

リーダーがカスタマイズする必要のある変数を含むURLの例では、変数が強調表示されたコード形式を使用する必要があります。 デフォルトでは `+`を使用します。 ` https://:3000 / simple / `や ` http:/// +`のように。 ただし、ライブリンクでは、代わりに標準のマークダウンリンクスタイルを使用し、追加の書式設定は必要ありません。

ソフトウェア

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

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

マルチサーバー設定

技術的に明確にするために、マルチサーバーのセットアップにはプロジェクトの用語を使用します。 用語はプロジェクトからのものであることを明確にしてください。 例:「Djangoプロジェクトは、元のサーバーを* primary として、セカンダリサーバーを replica として参照します。 MySQLプロジェクトでは、元のサーバーを master 、セカンダリサーバーを slave *と呼びます。」

マルチサーバーアーキテクチャをより抽象的に説明する場合は、* primary replica または manager worker *という用語を使用します。

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

https://www.digitalocean.com/community/tutorials/technical-recommendations-and-best-practices-for-digitalocean-s-tutorials [技術的なベストプラクティスガイド]ガイドには、一貫した品質の作成に役立つガイダンスが含まれています。読者を支援するチュートリアル。

DigitalOceanの著者になるへのこのリンクに従ってください。