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

There are four sections in this guide:

  • Style 、テクニカルチュートリアルを作成するための高レベルのアプローチ
  • 構造、レイアウトとコンテンツの説明
  • Formatting, a Markdown reference guide
  • Terminology, a guide to common terms and word usage

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

You can use the Formatting section of this guide along with our Markdown previewer and How To Write a Proposal and Outline for a DigitalOcean Community Tutorial as references while writing your article.

We also have a technical best practices guide outlining our tech-focused recommendations.

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

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

スタイル

The style for DigitalOcean articles reflects our purpose in publishing them: to provide quality learning information for engineers and developers. We strive to ensure that all DigitalOcean tutorials are:

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

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

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

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

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

We avoid words like “simple,” “straightforward,” “easy,” “simply,” “obviously,” and “just,” as these words make assumptions about the reader’s knowledge. 著者はこれらの単語を使用して、読者がやりがいのあるトピックを推し進めるように促し、動機付けますが、多くの場合、逆の効果があります。 何かが「簡単」だと聞いた読者は、問題に遭遇したときにイライラするかもしれません。 代わりに、読者が成功するために必要な説明を提供することで、読者を励まします。

技術的に詳細で正しい

私たちの記事は技術的に正確であり、業界のベストプラクティスに従っています。 また、コードやコマンドだけでなく、詳細も提供します。 We don’t provide large blocks of configuration or program code and ask readers to paste it into their text editor, trusting us that it works and is safe. We provide all the details necessary for the readers to understand and trust the article.

すべてのコマンドには、必要に応じてオプションやフラグなど、詳細な説明が必要です。 Every block of code should be followed by prose explanations that describe what it does and why it works that way. When you ask the reader to execute a command or modify a configuration file, first explain what it does and why you’re asking the reader to make those changes. These details give readers the information they need to grow their skills.

Authors test their tutorials to ensure they work by following them exactly as written on fresh servers to ensure accuracy and identify missing steps. 私たちの編集者はまた、読者に素晴らしい学習体験を保証するために、レビュープロセスの一部としてこれらの記事をテストします。

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

Once a reader has finished a DigitalOcean article, they will have installed, built, or set up something from start to finish. 実用的なアプローチを強調します。記事の最後に、読者は使用可能な環境または構築するための例を用意する必要があります。

What this means for the writer is that the article should cover the topic thoroughly. Authors should link to existing DigitalOcean articles as prerequisites that readers will follow before beginning the tutorial and link to available DigitalOcean articles to provide additional information in the body of the tutorial. 著者は、既存のDigitalOcean記事がなく、短い要約で情報を記事に直接追加できない場合にのみ、情報を収集するために読者をオフサイトに送る必要があります。

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

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

Unlike blog posts, we do not use the first person singular (e.g., “I think …”). Instead, we encourage the use of the second person (e.g., “You will configure …”) to keep the focus on the reader and what they’ll accomplish. In some cases, we’ll use the first person plural (e.g., “We will examine …”).

私たちは、結果に焦点を当てた動機付けの言葉を奨励します。 For example, instead of “You will learn how to install Apache,” try “In this tutorial, you will install Apache.” This approach motivates the reader and focuses on the goal they need to accomplish.

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

構造

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

Most of the tutorials we publish are procedural, which walk the reader through accomplishing a task step-by-step. The structure for a procedural article looks like this:

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

Conceptual articles will have a title, an introduction, and a conclusion, but they might not have a prerequisites section or follow the “Step” convention:

  • タイトル（レベル1の見出し）
  • はじめに（レベル3の見出し）
  • 前提条件（オプション）（レベル2の見出し）
  • Subtopic 1 (Level 2 heading)
  • Subtopic 2 (Level 2 heading)
  • …
  • Subtopic n (Level 2 heading)
  • 結論（レベル2の見出し）

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

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

Our article templates have this structure already written for you in Markdown, and we encourage you to use these templates as a starting point for your own articles.

タイトル

タイトルを書くときは、チュートリアルに従って読者が何を達成するかを慎重に考えてください。 Try to include the goal of the tutorial in the title, not just the tool(s) the reader will use to accomplish that goal. Ideally, titles will be under 60 characters long.

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

たとえば、チュートリアルがCaddy Webサーバーのインストールに関するものである場合、目標はWebサイトをホストする可能性があります。 If your tutorial is about installing Fail2Ban, the goal might be to protect an Nginx server.

Titles that include the goal (like “How To Host a Website Using Cloudflare and Nginx on Ubuntu 22.04”) are generally more informative for the reader than titles that don’t (like “How To Use Cloudflare and Nginx on Ubuntu 22.04”).

序章

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

  • What is the tutorial about? What software is involved and what does each component do (briefly)?
  • 読者がこのトピックを学ぶ必要があるのはなぜですか？この構成でこの特定のソフトウェアを使用する利点は何ですか？ 読者がこのチュートリアルに従う必要がある実際的な理由は何ですか？
  • このチュートリアルで読者は何をするか、作成しますか？サーバーをセットアップしてからテストしていますか？ 彼らはアプリを構築して展開していますか？ 具体的に説明してください。これにより、読者が必要とする動機付けが提供され、トピックに興奮するようになります。
  • 読者はそれらが完了したときに何を達成しますか？彼らはどのような新しいスキルを持ちますか？ 以前はできなかったことができるでしょうか。

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

読者と彼らが何を成し遂げるかに焦点を合わせ続けてください。 Instead of using phrases like “we will learn how to,” use phrases like “you will configure” or “you will build.” This goes a long way to motivate the reader and get them excited about your topic. さらに、テクノロジーではなく、読者が解決している問題に焦点を合わせ続けます。 For example, if a tutorial is about building a project with React, you can focus your introduction on the project rather than explaining what React is.

前提条件

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

目的は、読者が現在のチュートリアルに従う前に、読者が何をすべきか、または何をすべきかを正確に詳しく説明することです。 The format is a list that the reader can use as a checklist. Each point must link to an existing DigitalOcean tutorial that covers the necessary content or the official product documentation if there are no current DigitalOcean tutorials. This allows you to rely on existing content that is known to work instead of starting from scratch.

私たちのシステムと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サーバーへのデプロイに関するチュートリアルには、次の前提条件があります。

前提条件

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

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

When you test your tutorial, follow all of the prerequisite tutorials exactly as written so that everyone uses the same starting point. If you change a variable or complete an optional step from one of the prerequisites, make sure to note that.

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

前提条件を具体的に示してください。 特定の何かへのリンクがない「JavaScriptに精通している」などの前提条件は、読者に多くのコンテキストを提供しません。 Instead, list specific concepts the reader should know and provide them with resources that help them get up to speed so they can successfully complete your tutorial. For example, use something like “Familiarity with Javascript. To build your skills, check out the How To Code in JavaScript series.”

手順

The Step sections are the parts of your tutorial where you describe what the reader needs to do and why. ステップには、コマンド、コードリスト、およびファイルが含まれ、何をするかだけでなく、なぜこのようにするのかを説明する説明が提供されます。

Each step begins with a level 2 heading.

Procedural tutorials start each step title with the word Step and a number, followed by an em-dash. The step title describes what readers will accomplish in that step and uses a gerund (-ing words), like so:

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

タイトルの後に、読者が各ステップで何をするか、およびチュートリアルの全体的な目標を達成するために読者が果たす役割を説明する紹介文を追加します。 読者に焦点を合わせます。 Instead of phrases like “We will learn” or “I will explain,” use phrases like “You will build” or “you will create.”

ステップのコマンド

All commands a reader must run should be on their own line in their own code block, and each command should be preceded by a description that explains what the command does. After the command, provide additional details about the command, such as what the arguments do and why your reader is using them.

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

  1. ls -al /home/sammy

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

You should display the output of commands and programs using a separate code block, such as the following example:

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

  1. node hello.js

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

Output
Hello world!
This is my first Node.js program!

The output block has a label and is separated from the command with some text that explains the output. コマンドを出力から分離すると、コマンドがどこで終了し、出力がどこで開始するかが読者にとってより明確になります。

If readers will be moving between directories, be sure to provide the command(s) necessary for those movements.

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

コマンドと同様に、常にその一般的な目的を説明することによってファイルまたはスクリプトを紹介し、次にリーダーがファイルに加える変更を説明します。 Without these explanations, readers won’t be able to customize, update, or troubleshoot issues.

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

On tutorials that are targeted to command-line users, instruct the reader to create and open the file using a command on its own line:

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

  1. nano /etc/nginx/sites-available/default

を使用します nano すでにインストールされているUbuntuおよびDebianチュートリアル用のエディター。 を使用しております vi CentOSとFreeBSDのチュートリアルについて。 いずれの場合も、使用は避けてください touch to create new empty files, as your readers can create files with the editor directly.

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

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

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

コードブロック

We treat all code as an opportunity for learning. If you’re asking the reader to write code, follow the same approach as for commands: introduce the code block with a high-level explanation of what it does. 次に、コードを表示してから、重要な詳細を呼び出します。

次に例を示します。

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

  1. nano hello.js

Add the following code to the file, which prints a message to the screen:

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

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

Note that the code block has a label that clearly shows the filename.

This Docker Swarm tutorial is a good example of how to use our custom Markdown to distinguish between commands run on several different servers, as well as locally.

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

ファイルを開く /etc/nginx/sites-available/default エディターで：

  1. 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;
...

}

Be sure to explain what the change does and why it’s necessary.

DigitalOcean’s custom Markdown and formatting guidelines are designed to help make our tutorials’ instructions as easy to read as possible.

Transitions

Each step should be framed with a brief introductory sentence and a closing transition sentence that describes what the reader accomplished and where they are going next. Transitions guide the reader and provide important context for instructions, commands, and output. To avoid repetition, vary the language used for these sentences so that it does not reiterate the step titles.

Here is an example of a transition at the end of Step 1 in this tutorial on How To Secure Nginx with Let’s Encrypt on Rocky Linux 8:

You have now installed the Let’s Encrypt client, but before obtaining certificates, you need to make sure that all required ports are open. To do this, you will update your firewall settings in the next step.

In the example above, the author summarized what the reader achieved, introduced the next task, and explained how the two steps are connected.

Framing each step in this way helps readers learn and motivates them to keep going.

結論

チュートリアルの結論は、読者がチュートリアルに従って達成したことを要約する必要があります。 Instead of using phrases like “we learned how to,” use phrases like “you configured” or “you built.”

The conclusion should also describe what the reader can do next, which can include a description of use cases or features the reader can explore, links to other DigitalOcean tutorials with additional setup or configuration, and links to external documentation.

Some good examples include this Kubernetes tutorial’s conclusion and this node-csv tutorial’s conclusion.

フォーマット

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

ヘッダー

Each section of our tutorials has a corresponding header: the title should be an H1 header; the introduction should be an H3 header; prerequisites, steps, and conclusion should have H2 headers. この形式は、Markdown記事テンプレートで確認できます。

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

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

H3ヘッダーは慎重に使用し、H4ヘッダーは避けてください。 サブヘッダーを使用する必要がある場合は、チュートリアルのそのセクション内にそのレベルのヘッダーが2つ以上あることを確認してください。 Alternatively, consider making multiple steps.

行レベルのフォーマット

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

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

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

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

  • コマンド名、 unzip
  • のようなパッケージ名 mysql-server
  • オプションのコマンド
  • 次のようなファイル名とパス ~/.ssh/authorized_keys
  • 次のようなURLの例 http://your_domain
  • のようなポート :3000
  • Key presses, which should be in ALL CAPS, like ENTER. If keys need to be pressed simultaneously, use a plus symbol (+), such as CTRL+C.

コードブロック

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

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

省略記号を使用してファイルの抜粋と省略を示します（ 。 . .). If the reader needs to make any changes, use highlighting:

/ 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;
...

}

If most of a file can be left with the default settings, we typically show just the section that needs to be changed.

If readers are adding lines to pre-existing code, use highlighting to indicate the new lines or other changes. Here’s an example from the tutorial, How To Use Go Modules.

Open your main.go file from the mymodule directory and add a call to PrintHello by adding the highlighted lines below:

projects/mymodule/main.go

package main

import (
	"fmt"

	"mymodule/mypackage"
)

func main() {
	fmt.Println("Hello, Modules!")

	mypackage.PrintHello()
}

In the example above, the items that a reader will add are all highlighted.

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

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

```command
sudo apt update
```

```super_user
adduser sammy
```

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

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

  1. sudo apt update



  1. adduser sammy



  1. FLUSH PRIVILEGES;

When you present the commands this way, readers won’t be able to accidentally select the prompt characters.

コードブロックラベル

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!
```

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

Output
Hello World!

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

コードブロック環境の色

ローカルマシンや複数のサーバーなど、複数のコンピューターでリーダーを動作させる場合があります。 Using different colors for the environment display can make this easier for readers to follow. DigitalOceanのMarkdownを使用すると、次の行を追加してコードブロックの背景に色を付けることができます。 [environment name] ブロック内のどこでも。 のオプション name それは local, second, third, fourth、 と fifth.

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

  1. ssh root@your_server_ip

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

使用する [environment second] このように見えます：

  1. echo "Secondary server"

使用する [environment third] このように見えます：

  1. echo "Third server"

使用する [environment fourth] このように見えます：

  1. echo "Fourth server"

と [environment fifth]は次のようになります：

  1. echo "Fifth server

Use these colors in multi-server or multi-environment tutorials. Where necessary, you can stack an environment label and an output label to indicate a file within a different environment, like this sample Output block in a local environment:

  1. Output
    Hello World!

Nested labels ensure that the reader has all the requisite information to run commands in the appropriate terminal session.

注意と警告

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

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

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

注：これは注です。

警告：これは警告です。

DigitalOcean固有の情報

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

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

変数

Highlight any items that the reader needs to change, like example URLs, version numbers, or modified lines in configuration files. あなたは私たちの習慣で単語や行を囲むことによってこれを行うことができます <^> マークダウン。

Here’s an example from the Initial Server Setup with Ubuntu 22.04:

This example creates a new user called sammy, but you should replace that with a username that you like:

  1. adduser sammy

Note: You cannot highlight multiple lines with one pair of symbols, so you need to highlight each line individually. Occasionally a symbol like a shebang (#) or a backtick might break the highlighting feature in the line, and you may need to have two highlighted sections on the same line.

通常も使用するコンテキストで変数を参照する場合 in-line code フォーマット、あなたは使用する必要があります both styles. Make sure your tutorial is as accessible as possible by using language like “highlighted in the preceding code block” instead of “highlighted in red above.”

Avoid language like “highlighted in yellow,” as highlighting colors might change.

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

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

When including images in your tutorial, please follow these guidelines:

  • スクリーンリーダーを使用している読者が画像ではなく代替テキストに依存できるように、説明的な代替テキストを含めます。
  • Include a brief caption to contextualize the image within the context of the article (the caption will typically be shorter than alt text).
  • 使用 .png ファイル形式。
  • imgurで画像をホストします。
  • 高さをできるだけ短くして画像を作成します。

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

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

![Descriptive alt text for screen readers](http://imgur.com/your_image_url “Brief caption here”)

You can review examples of strong descriptive alt text in the images in this Matomo tutorial.

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

用語

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

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

Our default example username is sammy. You can also choose something descriptive where helpful, like webdav-kai また nsd.

The default hostname is your_server, though you may want to choose something more descriptive in multi-server setups, such as django\_replica\_1.

The default domain is your_domain. For multi-server setups, you can choose something like primary-1.your_domain また replica-1.your_domain. While example.com is a valid domain for documentation, using your_domain in tutorials makes clear that the reader should change the domain in examples.

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

設定ファイルの例
ip: your_server_ip
domain: primary-1.your_domain

This makes it clear to readers that there is something they should change.

IPアドレスとURL

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

リーダーがカスタマイズする必要のある変数を含むURLの例では、変数を強調表示したコードフォーマットを使用する必要があります。 デフォルトでは your_domain, like https://your_domain:3000/simple/ また http://your_server_ip/. However, live links should use the standard Markdown link style with no extra formatting.

ソフトウェア

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

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

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

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

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

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

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

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