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

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

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

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

すばやく公開するには、DigitalOceanコミュニティの作成者はスタイルと構造のセクション全体を読む必要があります。 templatesは記事の開始点として役立ち、このガイドのフォーマットセクションとMarkdown previewerは、執筆中の参照として使用できます。また、技術に焦点を当てた推奨事項にはtechnical best practices guideがあります。

スタイル

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

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

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

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

技術的に詳細で正しい

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

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

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

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

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

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

構造

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

タイトル
前書き
目標（オプション）
前提条件
ステップ1 —最初のことをする
ステップ2 —次のことをする
…
ステップn —最後のことをする
結論

私たちのarticle templatesは、Markdownにこのレイアウトがあり、独自の記事の開始点として使用できます。 Formatting section of this guideには、フォーマット規則に関する詳細があります。

タイトル

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

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

たとえば、チュートリアルがCaddyのインストールに関するものである場合、目標はhost a websiteになる可能性があります。チュートリアルがFreeIPAのインストールに関するものである場合、目標はset up centralized Linux authenticationになる可能性があります。目標を含むタイトル（「https://www.digitalocean.com/community/tutorials/how-to-create-a-status-page-with-cachet-on-debian-8 [ステータスページの作成方法Debian 8でCachetを使用]]）は一般的に、そうでないタイトルよりも読者にとって有益です（「Debian 8でCachetをインストールおよび設定する方法」など）。

はじめにと目標

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

チュートリアルの目標は何ですか？彼らがそれに従うならば、読者は何を達成しますか？
どのソフトウェアが関与しており、各コンポーネントは何をしますか（簡単に）？
この構成でこの特定のソフトウェアを使用する利点は何ですか？読者がこのチュートリアルに従うべき実用的な理由は何ですか？

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

いくつかの良い例には、this Prometheus tutorial’s introductionとthis Pydio tutorial’s goalsが含まれます。

前提条件

DigitalOceanチュートリアルのPrerequisitesセクションには、非常に特殊な形式と目的があります。

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

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

配布、サーバーの初期セットアップ、およびその他の必要なオプション（メモリ要件、DO APIキー、IPv6、プライベートネットワークなど）を含む、必要なサーバーの数。
ソフトウェアのインストールと構成。
必要なDNS設定またはSSL証明書。
GitHub、Facebook、Twitter、または読者が必要とする他のサービスなどの追加のユーザーアカウント。

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

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

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

Ubuntu 16.04サーバー、ソフトウェアのインストール、およびthis Minio tutorial’s prerequisitesのDNSレコード。
CentOS 7サーバーとDNSレコード（this FreeIPA tutorial’s prerequisites）。
this Cachet tutorial’s prerequisitesの他のチュートリアルの部分的な手順を使用したメモリ要件とソフトウェアセットアップを備えたDebian8サーバー。
this Nagios and Alerta tutorial’s prerequisitesのソフトウェアインストールで複数のサーバーを処理します。

ステップ

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

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

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

DigitalOceanのcustom Markdown and formatting guidelinesは、チュートリアルの説明をできるだけ読みやすくするために設計されています。 This Docker Swarm tutorialは、カスタムMarkdownを使用して、ローカルだけでなく複数の異なるサーバーで実行されるコマンドを区別する方法の良い例です。

結論

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

いくつかの良い例には、this LXD tutorial’s conclusion、https：//www.digitalocean.com/community/tutorials/how-to-monitor-cpu-use-on-digitalocean-droplets#conclusion [このCPU監視チュートリアルの結論]、およびthis Mosquitto tutorial’s conclusion。

フォーマット

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

ヘッダ

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

手続き型チュートリアルの場合、ステップヘッダーには、ステップ番号（数値）とそれに続く全角ダッシュ（—）を含める必要があります。ステップヘッダーでも、-ingの単語である動名詞を使用する必要があります。ステップヘッダーの例はStep 1 — Installing Nginxです。

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

行レベルの書式設定

Bold textは次の目的で使用する必要があります。

表示されるGUIテキスト
wordpress-1やsammyなどのホスト名とユーザー名
用語リスト
新しいサーバーまたはユーザーへの切り替えなど、コマンドのコンテキストを変更する際の強調

Italicsは、専門用語を導入する場合にのみ使用してください。たとえば、Nginxサーバーはload balancerになります。

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

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

コードブロック

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

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

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

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

コードブロックにコマンドプロンプトを含めないでください。代わりに、非ルートユーザーコマンド、ルートユーザーコマンド、カスタムプレフィックスにそれぞれ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]の行を追加することにより、コードブロックにラベルを追加できます。

ラベルを使用して、ファイルの内容を含むコードブロックをファイル名でマークします。 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のMarkdownを使用すると、ブロック内の任意の場所に[environment name]の行を追加することで、コードブロックの背景に色を付けることができます。 nameのオプションは、local、second、third、fourth、およびfifthです。

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

ssh root@your_server_ip

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

echo "Secondary server"

echo "Third server"

echo "Fourth server"

echo "Fifth server

注意と警告

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

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

Notes and Warnings

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

[.note]＃Note:これはメモです。
＃

[.warning]＃Warning:これは警告です。
＃

変数

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アドレスを説明する必要がある場合は、one of the two blocks reserved for documentation as per RFC-5737のアドレスを使用してください。具体的には、パブリックアドレスなどの203.0.113.0/24と、プライベートアドレスなどの198.51.100.0/24をお勧めします。

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

ソフトウェア

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

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

マルチサーバー設定

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

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

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

technical best practices guideガイドには、読者に役立つ一貫性のある高品質のチュートリアルを作成するのに役立つガイダンスが含まれています。

このリンクをたどってbecome a DigitalOcean authorにアクセスしてください。

TOC