DigitalOcean的技术写作指南

DigitalOcean is excited to continue building out its collection of technical articles related to server administration and software engineering. To ensure that DigitalOcean articles have consistent quality and style, we have developed the following guidelines.

DigitalOcean很高兴继续建立与服务器管理和软件工程有关的技术文章集。 为确保DigitalOcean文章具有一致的质量和样式，我们制定了以下准则。

There are three sections in this guide:

本指南分为三个部分：

• Style, our high-level approach to writing technical tutorials

  Style ，我们编写技术教程的高级方法

• Structure, an explanation of our layout and content

  结构 ，说明我们的布局和内容

• Formatting and Terminology, a Markdown and terminology reference

  格式和术语 ，降价和术语参考

To get published quickly, we recommend that you read the Style and Structure sections in their entirety before you begin working on your article.

为了快速发布，我们建议您在开始撰写文章之前先完整阅读“ 样式和结构”部分。

Our templates are useful as a starting point for an article, and we encourage you to start your draft with this template.

我们的模板对于作为文章的起点很有用，我们鼓励您使用此模板开始草稿。

You can use the Formatting section of this guide along with our Markdown previewer as references while writing your article.

在撰写文章时，您可以将本指南的“ 格式设置”部分与我们的Markdown预览器一起用作参考。

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

我们还有一个技术最佳实践指南 ，概述了我们针对技术的建议。

Read on to learn about our article style.

继续阅读以了解我们的文章风格。

---

---

样式 (Style)

DigitalOcean articles don’t use a particular style manual like the Chicago Manual of Style. Instead, we strive to ensure all DigitalOcean tutorials are:

DigitalOcean文章不使用特定的样式手册，例如《芝加哥样式手册》。 相反，我们努力确保所有DigitalOcean教程均为：

• Comprehensive and written for all experience levels

  综合和书面的所有经验水平

• Technically detailed and correct

  技术上详细且正确

• Practical, useful, and self-contained

  实用，有用且自成体系

• Friendly but formal

  友好但正式

These principles guide authors to create articles, tutorials, and other learning materials that help people solve their problems and grow as developers.

这些原则指导作者创建文章，教程和其他学习材料，以帮助人们解决问题并成长为开发人员。

综合和书面的所有经验水平 (Comprehensive and written for all experience levels)

Our articles are written to be as clear and detailed as possible without making assumptions about the reader’s background knowledge.

我们的文章写得尽可能清晰和详细，而无需假设读者的背景知识。

We explicitly include every command a reader needs to go from their first SSH connection on a brand new server to the final, working setup. We also provide readers with all of the explanations and background information they need to understand the tutorial. The goal is for our readers to learn the concepts, not just copy and paste code and commands.

我们明确地包含了读者从全新服务器上的第一个SSH连接到最终正常工作所需的所有命令。 我们还将为读者提供他们理解本教程所需的所有解释和背景信息。 目的是让我们的读者学习概念，而不仅仅是复制和粘贴代码和命令。

We avoid words like “simple,” "straightforward,” "easy,” “simply,” “obviously,” and “just,” as these words do make assumptions about the reader’s knowledge. While authors use these words to encourage and motivate readers to push through challenging topics, they often have the opposite effect; a reader who hears that something is “easy” may be frustrated when they encounter an issue. Instead, we encourage our readers by providing the explanations they need to be successful.

我们避免使用“简单”，“直截了当”，“简单”，“简单”，“明显”和“公正”之类的词语，因为这些词语确实对读者的知识做出了假设。 尽管作者使用这些词来鼓励和激励读者推动具有挑战性的话题，但它们往往产生相反的效果； 听到某事“轻松”的读者在遇到问题时可能会感到沮丧。 相反，我们通过提供成功所需的解释来鼓励读者。

技术上详细且正确 (Technically detailed and correct)

Our articles are technically accurate and follow industry best-practices. They also provide more details than just the code and commands. 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. We provide all the details necessary for the readers to understand it.

我们的文章在技术上准确无误，并遵循行业最佳实践。 它们还提供了不仅仅是代码和命令的更多细节。 我们不会提供大量的配置或程序代码，而是请读者将其粘贴到他们的文本编辑器中，并相信我们可以使用。 我们提供所有必要的细节，以使读者理解它。

Every command should have a detailed explanation, including options and flags as necessary. Every block of code should 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 background they need to grow their skills.

每个命令应有详细的说明，必要时还包括选项和标志。 每个代码块都应该描述它的作用以及为什么这样做。 当您要求读者执行命令或修改配置文件时，请首先说明其作用以及为什么要读者进行这些更改。 这些细节为读者提供了发展技能所需的背景。

Authors test their tutorials to ensure they work by following them exactly as written on fresh servers. This ensures accuracy and identifies missing steps. Our editors also test these articles as part of the review process to ensure a great learning experience for the reader.

作者测试他们的教程，以确保完全按照新服务器上编写的内容进行操作，以确保它们能正常工作。 这样可以确保准确性并确定缺少的步骤。 我们的编辑还将这些文章作为审阅过程的一部分进行测试，以确保为读者提供良好的学习体验。

实用，有用且自成体系 (Practical, useful, and self-contained)

Once a reader has finished a DigitalOcean article, they should have installed, built, or set up something from start to finish. We emphasize a practical approach: at the end of an article, the reader should have a usable environment or an example to build upon.

读者完成DigitalOcean文章后，应该从头到尾都已经安装，构建或设置了一些东西。 我们强调一种实用的方法：在文章的结尾，读者应该有一个可用的环境或一个可以借鉴的例子。

What this means for the writer is that their article should cover the topic thoroughly. Authors should link to existing DigitalOcean articles, if available, to set up prerequisites that readers should follow before beginning the tutorial, and link to available DigitalOcean articles to provide additional information in the body of the tutorial. Authors should only send readers offsite to gather information if there’s no existing DigitalOcean article and the information can’t easily be added to the article directly.

对于作者而言，这意味着他们的文章应彻底涵盖该主题。 作者应链接到现有DigitalOcean文章(如果有)，以设置读者在开始本教程之前应遵循的先决条件，并链接到可用DigitalOcean文章以在本教程的主体中提供其他信息。 如果没有DigitalOcean现有文章，并且信息无法轻松地直接添加到文章中，作者只能将读者发送到异地收集信息。

友好但正式 (Friendly but formal)

Our tutorials aim for a friendly but formal tone. This means that articles do not include jargon, memes, slang, or excessive slang, emoji, or jokes. As we’re writing for a global audience, we aim for a tone that works across language and cultural boundaries.

我们的教程旨在营造友好而正式的语气。 这意味着文章不包含行话，模因，语或过多的lang语，表情符号或笑话。 在为全球读者写作时，我们的目标是营造一种跨越语言和文化边界的语气。

Unlike blog posts, we do not use the first person singular (e.g. “I think …”). Instead, we encourage the use 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 install …”“).

与博客文章不同，我们不使用第一人称单数(例如“我认为...”)。 相反，我们鼓励使用第二个人(例如，“您将配置...”)来专注于读者及其将完成的工作。 在某些情况下，我们将使用第一人称复数形式(例如，“我们将安装...””)。

We encourage motivational language focused on outcomes. For example, instead of "You will learn how to install Apache”, try “In this tutorial you will install Apache”. This motivates the reader and focuses on the goal they need to accomplish.

我们鼓励注重结果的激励性语言。 例如，请尝试“在本教程中将安装Apache”，而不是“您将学习如何安装Apache”。这可以激发读者的注意力，并着重于他们需要实现的目标。

Finally, the language of our tutorials honors diverse human experiences and follow our Community Code of Conduct. That means we avoid offensive language or other content that is in reference to (but not limited to) age, disability, ethnicity, gender identity or expression, level of experience, nationality, neurodiversity, personal appearance, race, religion, political affiliation, sexual orientation, socioeconomic status, or technology choices.

最后，我们的教程语言表彰了各种人类经验，并遵循我们的社区行为准则 。 这意味着我们应避免使用涉及(但不限于)年龄，残障，种族，性别认同或表达，经验水平，国籍，神经多样性，个人面貌，种族，宗教，政治派别，性的冒犯性语言或其他内容方向，社会经济地位或技术选择。

---

---

结构体 (Structure)

DigitalOcean articles have a consistent structure comprised of the following sections:

DigitalOcean文章具有一致的结构，包括以下部分：

• Title
  标题
• Introduction
  介绍
• Goals (Optional)
  目标(可选)
• Prerequisites
  先决条件
• Step 1 — Doing the First Thing
  第1步-做第一件事
• Step 2 — Doing the Next Thing
  第2步-做下一件事
• …
  …
• Step n — Doing the Last Thing
  步骤n —做最后一件事
• Conclusion
  结论

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

我们的文章模板已经在Markdown中为您编写了此结构，我们鼓励您使用此模板作为自己文章的起点。

标题 (Title)

A typical title follows this format: How To <Accomplish a Task> with <Software> on <Distro>.

典型的标题采用以下格式： 如何在<Distro>上使用<Software> <完成任务> 。

When you write your title, think carefully about what the reader will accomplish by following your tutorial. Try to include the goal of the tutorial in the title, not just the tool(s) the reader will use to accomplish that goal.

撰写标题时，请仔细阅读本教程，仔细考虑读者将要完成的工作。 尝试在标题中包括本教程的目标，而不仅仅是读者用来实现该目标的工具。

For example, if your tutorial is about installing the Caddy web server, the goal is likely to host a website. If your tutorial is about installing FreeIPA, the goal might be to set up centralized Linux authentication. Titles that include the goal (like “How To Create a Status Page with Cachet on Debian 8”) are generally more informative for the reader than titles that don’t (like “How To Install and Set Up Cachet on Debian 8”).

例如，如果您的教程是关于安装Caddy Web服务器的，则目标可能是托管网站 。 如果您的教程是关于安装FreeIPA的，则目标可能是设置集中式Linux身份验证 。 包含目标的标题(如“ 如何在Debian 8上使用Cachet创建状态页 ”)通常比不包含目标的标题(如“ 如何在Debian 8上安装和设置Cachet”)提供更多信息。

介绍 (Introduction)

The first section of every article is the Introduction, which is usually one to three paragraphs long. The purpose of the introduction is to motivate the reader, set expectations, and summarize what the reader will do in the article. Your introduction should answer the following questions:

每篇文章的第一部分是“ 简介” ，通常长一到三段。 简介的目的是激励读者，设定期望并总结读者在本文中的工作。 您的介绍应回答以下问题：

• What is the tutorial about? What software is involved, and what does each component do (briefly)?

  教程是关于什么的？ 涉及什么软件，每个组件(简要地)做什么？

• Why should the reader learn this topic? What are the benefits of using this particular software in this configuration? What are some practical reasons why the reader should follow this tutorial?

  读者为什么要学习这个话题？ 在此配置中使用此特定软件有什么好处？ 读者应遵循本教程的一些实际原因是什么？

• What will the reader do or create in this tutorial? Are they setting up a server and then testing it? Are they building an app and deploying it? Be specific, as this provides the motivation readers need and gets them excited about the topic.

  读者将在本教程中做什么或创建什么？ 他们是在设置服务器然后对其进行测试吗？ 他们在构建应用程序并进行部署吗？ 要具体，因为这提供了读者所需的动力并使他们对该主题感到兴奋。

• What will the reader have accomplished when they’re done? What new skills will they have? What will they be able to do that they couldn’t do before?

  读者完成后会取得什么成就？ 他们将拥有哪些新技能？ 他们将能够做以前无法做的事情？

Answering these questions in your introduction will also help you design a clear and reader-focused tutorial, as you’ll align the steps

在介绍中回答这些问题也将帮助您设计一个清晰且以读者为中心的教程，因为您将按照步骤进行操作

Keep the focus on the reader and what they will accomplish. 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.

继续关注读者及其成就。 不要使用诸如“您将配置”或“将要构建”之类的短语，而不必使用诸如“我们将学习如何做”之类的短语。 这可以极大地激发读者的积极性，并使他们对您的话题感到兴奋。

目标 (Goals)

Some larger tutorials use the optional Goals section to separate the tutorial’s context, background explanation, and motivation from the details of the final configuration. You should only use this section if your tutorial requires multiple servers, has a large software stack, or otherwise has a particularly complicated purpose, method, or result.

一些较大的教程使用可选的“ 目标”部分将教程的上下文，背景说明和动机与最终配置的细节分开。 仅在您的教程需要多个服务器，软件堆栈很大或其他目的，方法或结果特别复杂的情况下，才应使用此部分。

Some good examples include this Prometheus tutorial’s introduction and this Pydio tutorial’s goals.

一些很好的例子包括Prometheus教程的简介和Pydio教程的目标 。

Most tutorials will not have a Goals section.

大多数教程都没有“ 目标”部分。

先决条件 (Prerequisites)

The Prerequisites sections of DigitalOcean articles have a very specific format and purpose.

DigitalOcean文章的前提条件部分具有非常特定的格式和目的。

The purpose is to spell out exactly what the reader should have or do before they follow the current tutorial. The format is a bulleted list that the reader can use as a checklist. Each bullet point must link to an existing DigitalOcean tutorial that covers the necessary content if one exists. This allows you to rely on existing content known to work instead of starting from scratch.

目的是准确阐明读者在遵循当前教程之前应该做的事情。 该格式是项目符号列表，读者可以将其用作清单。 每个项目要点必须链接到现有的DigitalOcean教程，其中涵盖了必要的内容(如果存在)。 这使您可以依靠现有的已知有效内容，而不必从头开始。

Common prerequisite bullet points include:

常见的先决条件要点包括：

• The number of servers necessary, including distribution, initial server setup, and any additional necessary options (like memory requirements, DO API keys, IPv6, or private networking).
  所需的服务器数量，包括分发，初始服务器设置以及任何其他必需的选项(例如内存要求，DO API密钥，IPv6或专用网络)。
• Software installation and configuration.
  软件安装和配置。
• Required DNS settings or SSL certificates.
  必需的DNS设置或SSL证书。
• Additional user accounts like GitHub, Facebook, Twitter, or other services your reader will need.
  其他用户帐户，例如GitHub，Facebook，Twitter或读者需要的其他服务。

Our systems and DevOps tutorials take the reader from a fresh deployment of a vanilla distribution image to a working setup, so they should start with the first SSH connection to the server or include a prerequisite tutorial that does.

我们的系统和DevOps教程将读者从全新分发的原始分发映像带入工作设置，因此它们应该从与服务器的第一个SSH连接开始，或者包括一个先决条件的教程。

Our software development tutorials work in a similar fashion, providing the reader with all of the prerequisites they’ll need up front, including a prerequisite for the development environment.

我们的软件开发教程以类似的方式工作，为读者提供了他们首先需要的所有先决条件，包括开发环境的先决条件。

For example, a tutorial about building and deploying a Node.js application and deploying it to an Ubuntu server using Git might have the following prerequisites:

例如，有关使用Git构建和部署Node.js应用程序并将其部署到Ubuntu服务器的教程可能具有以下先决条件：

先决条件 (Prerequisites)

To complete this tutorial, you will need:

要完成本教程，您将需要：

• One Ubuntu 18.04 server set up by following the Ubuntu 18.04 initial server setup guide, including a non-root sudo-enabled user and a firewall.

  遵循Ubuntu 18.04初始服务器设置指南来设置一台Ubuntu 18.04服务器，包括未启用root用户的sudo用户和防火墙。

• A domain name configured to point to your server. You can learn how to point domains to DigitalOcean Droplets by following the How To Set Up a Host Name with DigitalOcean tutorial.

  配置为指向您的服务器的域名。 您可以按照如何使用DigitalOcean设置主机名教程来学习如何将域指向DigitalOcean Droplet。

• Git installed on your local machine. You can follow the tutorial Contributing to Open Source: Getting Started with Git to install and set up Git on your computer.

  安装在本地计算机上的Git。 您可以按照教程“ 贡献给开源：Git入门”在计算机上安装和设置Git。

• A local development environment for Node.js. Follow How to Install Node.js and Create a Local Development Environment.

  Node.js的本地开发环境。 遵循如何安装Node.js和创建本地开发环境 。

By reading the prerequisites, your reader knows exactly what they need to do before they start. There are no surprises.

通过阅读先决条件，您的读者可以确切地知道他们在开始之前需要做什么。 没有惊喜。

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

在测试教程时，请确保完全按照书面要求遵循所有先决条件教程，以便每个人都使用相同的起点。 如果您更改了某个变量或从先决条件之一完成了可选步骤，请务必注意。

You can see good prerequisites examples for:

您可以看到以下方面的良好先决条件示例：

• Ubuntu 16.04 servers, software installation, and DNS records in this Minio tutorial’s prerequisites.

  本Minio教程的先决条件中的 Ubuntu 16.04服务器，软件安装和DNS记录。

• CentOS 7 servers and DNS records in this FreeIPA tutorial’s prerequisites.

  FreeIPA教程的先决条件中的 CentOS 7服务器和DNS记录。

• Debian 8 servers with memory requirements and software setup using partial steps from other tutorials in this Cachet tutorial’s prerequisites.

  具有该内存要求和软件设置的Debian 8服务器，使用Cachet教程先决条件中其他教程的部分步骤。

• Handling multiple servers with software installation in this Nagios and Alerta tutorial’s prerequisites.

  Nagios和Alerta教程的先决条件中处理带有软件安装的多台服务器。

Be specific with your prerequisites. A prerequisite like “Familiarity with JavaScript” without a link to something specific doesn’t give your reader much context. Instead, consider listing 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.

具体说明您的先决条件。 诸如“ JavaScript熟悉”之类的前提条件没有链接到特定内容不会给您的读者带来太多的背景知识。 相反，请考虑列出读者应该知道的特定概念，并为他们提供帮助他们快速入门的资源，以便他们可以成功完成本教程。

脚步 (Steps)

The Step sections are the parts of your tutorial where you describe what the reader needs to do. A step contains commands, code listings, and files, and provides explanations that not only explain what to do but also why your’re doing it this way.

步骤部分是教程的各个部分，在其中描述读者需要做的事情。 一个步骤包含命令，代码清单和文件，并提供说明，这些说明不仅解释要做什么，而且还解释了 为什么要这样做。

Each step begins with a level 2 heading and use the gerund, which are -ing words.

每个步骤均以2级标题开头，并使用gerund(即-ing单词)。

Procedural tutorials should start each step title with the word Step and a number, followed by an em-dash:

过程性教程应在每个步骤标题的开头加上单词Step和一个数字，后跟一个破折号：

第1步–创建用户帐户 (Step 1 – Creating User Accounts)

After the title, add an introductory sentence that describes what the reader will do in each step and what role it plays in achieving the overall goal of the tutorial. Focus on the reader. Instead of phrases like “We will learn” or “I will explain”, use phrases like “You will build” or “you will create”.

在标题之后，添加一个介绍性句子，描述读者在每个步骤中将执行的操作以及它在实现教程的总体目标中所起的作用。 专注于读者。 代替“我们将学习”或“我将解释”之类的短语，而应使用“您将构建”或“您将创造”之类的短语。

End each step with a transition sentence that describes what the reader accomplished and where they are going next. Avoid repeating the step title in these introductions and transitions, and don’t start or end steps with contextless instructions, commands, or output.

在每个步骤的末尾都有一个过渡语句，该过渡语句描述了读者的成就以及下一步的发展方向。 避免在这些介绍和过渡中重复步骤标题，并且不要以无上下文的指令，命令或输出开始或结束步骤。

步骤中的命令和代码 (Commands and Code in Steps)

All commands in a step 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.

步骤中的所有命令应在各自的代码块中位于各自的行上，并且每个命令之前均应带有说明，以解释该命令的作用。 命令后，提供有关命令的其他详细信息，例如参数的作用以及读者使用它们的原因。

Execute the following command to display the contents of the /home/sammy directory, including all hidden files:

执行以下命令以显示/home/ sammy目录的内容，包括所有隐藏文件：

• ls -al /home/sammy

  ls -al / home / sammy

The -a switch shows all files, including hidden ones, and the -l switch shows a long listing including timestamps and file sizes.

-a开关显示所有文件，包括隐藏的文件， -l开关显示一长串，包括时间戳和文件大小。

Similarly, always introduce a file or script by describing its general purpose, then explain any changes that the reader will be making in the file. Without these explanations, readers won’t be able to customize, update, or troubleshoot their server in the long run.

同样，请始终通过描述文件或脚本的一般用途来介绍文件或脚本，然后说明读者将对文件或文件进行的任何更改。 如果没有这些说明，从长远来看，读者将无法自定义，更新服务器或对服务器进行故障排除。

Explicitly tell the user to create or open each file using a command on its own line.

明确告诉用户使用单独一行的命令来创建或打开每个文件。

Open the file /etc/hginx/config in your editor:

在编辑器中打开文件/etc/hginx/config ：

• nano /etc/nginx/config
  纳米/ etc / nginx / config

If you’re asking the reader to write code, follow the same approach for commands: introduce the code block with a high-level explanation of what it does. Then show the code, and then call out any important details:

如果您要求读者编写代码，请对命令执行相同的方法：引入代码块，并对其功能进行高级说明。 然后显示代码，然后调出所有重要的细节：

Create the file hello.js in your text editor:

在文本编辑器中创建文件hello.js ：

• nano hello.js
  纳米hello.js

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

将以下代码添加到在屏幕上显示消息的文件中：

hello.js

hello.js

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

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

The console.log function takes a string and prints it to the screen on its own line.

console.log函数接受一个字符串，并将其console.log打印到屏幕上。

Display the output of commands and programs using a code block as well, like the following example:

也使用代码块显示命令和程序的输出，如以下示例所示：

Run the hello.js program:

运行hello.js程序：

• node hello.js
  节点hello.js

You’ll see the following output:

您将看到以下输出：

    
    

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

DigitalOcean’s custom Markdown and formatting guidelines are designed to help make our tutorials’ instructions as easy to read as possible. 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.

DigitalOcean的自定义Markdown和格式指南旨在帮助使我们的教程说明尽可能易于阅读。 这份Docker Swarm教程是一个很好的示例，说明了如何使用我们的自定义Markdown来区分在多个不同服务器以及本地上运行的命令。

结论 (Conclusion)

The Conclusion of your tutorial should summarize what the reader has accomplished by following your tutorial. 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. This can include a description of use cases or features the reader can explore, links to other DigitalOcean tutorials with additional setup or configuration, and external documentation.

结论还应说明读者接下来可以做什么。 这可能包括对用例或读者可以探索的功能的描述，具有其他设置或配置的其他DigitalOcean教程的链接以及外部文档。

Some good examples include this LXD tutorial’s conclusion,this CPU monitoring tutorial’s conclusion, and this Mosquitto tutorial’s conclusion.

一些很好的例子包括该LXD教程的结论 ， 该CPU监视教程的结论和该Mosquitto教程的结论 。

---

---

格式化 (Formatting)

DigitalOcean tutorials are formatted in the Markdown markup language. Daring Fireball publishes a comprehensive Markdown guide if you’re unfamiliar with it. DigitalOcean also uses some custom Markdown. Examples of our custom Markdown are in the appropriate sections below.

DigitalOcean教程采用Markdown标记语言格式化。 如果您不熟悉Daring Fireball，则会发布全面的Markdown指南。 DigitalOcean还使用一些自定义Markdown 。 我们的自定义Markdown示例在下面的相应部分中。

标头 (Headers)

Each section of our tutorials has a corresponding header: the title should be an H1 header; the introduction should be an H3 header; the goals, prerequisites, steps, and conclusion should have H2 headers. You can see this format in our Markdown article templates.

我们教程的每个部分都有一个对应的标题：标题应为H1标题；标题应为H1标题。 简介应该是H3标头； 目标，前提条件，步骤和结论应具有H2标头。 您可以在我们的Markdown文章模板中看到这种格式。

For procedural tutorials, step headers should include step numbers (numerical) followed by an em dash (—).

对于过程性教程，步骤标题应包含步骤编号(数字)，后跟一个破折号( — )。

Step headers should also use the gerund, which are -ing words. An example step header is Step 1 — Installing Nginx.

步骤标题也应使用gerund，即-ing字。 步骤头示例是步骤1-安装Nginx 。

Use H3 headers sparingly, and avoid H4 headers. If you need to use subheaders, make sure there are two or more headers of that level within that section of the tutorial. Alternatively, consider making multiple steps instead.

谨慎使用H3标头，避免使用H4标头。 如果需要使用子标题，请确保在该教程的该部分中存在该级别的两个或多个标题。 另外，也可以考虑采取多个步骤。

行级格式化 (Line-level Formatting)

Bold text should be used for:

粗体字应用于：

• Visible GUI text
  可见的GUI文本

• Hostnames and usernames, like wordpress-1 or sammy

  主机名和用户名，例如wordpress-1或sammy

• Term lists
  术语表
• Emphasis when changing context for a command, like switching to a new server or user
  更改命令上下文时的重点，例如切换到新服务器或用户

Italics should only be used when introducing technical terms. For example, the Nginx server will be our load balancer.

斜体仅应在引入技术术语时使用。 例如，Nginx服务器将成为我们的负载均衡器 。

In-line code formatting should be used for:

内联代码格式应用于：

• Command names, like unzip

  命令名称，例如unzip

• Package names, like mysql-server

  包名称，例如mysql-server

• Optional commands
  可选命令

• File names and paths, like ~/.ssh/authorized_keys

  文件名和路径，例如~/.ssh/authorized_keys

• Example URLs, like http://your_domain

  网址示例，例如http:// your_domain

• Ports, like :3000

  端口，例如:3000

• Key presses, which should be in ALL CAPS and use a plus symbol, +, if keys need to be pressed simultaneously, like ENTER or CTRL+C

  按键，这应该是全部大写，并使用一个加号，+，如果键需要同时按下，像ENTER或CTRL+C

代码块 (Code Blocks)

Code blocks should be used for:

代码块应用于：

• Commands the reader needs to execute to complete the tutorial
  读者需要执行以完成教程的命令
• Files and scripts
  文件和脚本
• Terminal output
  终端输出
• Interactive dialogues that are in text
  文本形式的交互式对话

Excerpts and omissions in files can be indicated with ellipses (…). If most of a file can be left with the default settings, it’s usually better to show just the section that needs to be changed.

文件中的节选和遗漏可以用省略号( … )表示。 如果可以将大多数文件保留为默认设置，通常最好只显示需要更改的部分。

代码块前缀 (Code Block Prefixes)

Do not include the command prompt in the code block. Instead, use DigitalOcean’s custom Markdown for non-root user commands, root user commands, and custom prefixes, respectively:

不要在代码块中包括命令提示符。 而是将DigitalOcean的自定义Markdown分别用于非root用户命令，root用户命令和自定义前缀：

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

```super_user
adduser sammy
```

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

This is how the preceding examples look when rendered:

这是呈现上述示例时的外观：

• sudo apt-get update
  sudo apt-get更新

• adduser sammy
  adduser萨米

• FLUSH PRIVILEGES;
  冲洗特权;

代码块标签 (Code Block Labels)

DigitalOcean’s Markdown also includes labels and secondary labels. You can add labels to code blocks by adding a line with [label Label text] or [secondary_label Secondary label text] anywhere in the block.

DigitalOcean的Markdown还包括标签和辅助标签。 您可以通过在代码块中的任意位置添加带有[label Label text]或[secondary_label Secondary label text] [label Label text]的行来为代码块添加标签。

Use labels to mark code blocks containing the contents of a file with a filename. Use secondary labels to mark terminal output.

使用标签将包含文件内容的代码块标记为文件名。 使用辅助标签标记端子输出。

Labels look like this when rendered:

标签呈现时如下所示：

This is the label text

这是标签文字

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

Secondary label example:

次要标签示例：

   
   

    
    This is the secondary label text
   
   
This is some output from a command

代码块环境颜色 (Code Block Environment Colors)

DigitalOcean’s Markdown allows you to color the background of a code block by adding a line with [environment name] anywhere in the block. The options for name are local, second, third, fourth, and fifth.

DigitalOcean的Markdown允许您通过在代码块的任何位置添加带有[environment name ]的行来为代码块的背景着色。 name的选项是local ， second ， third ， fourth和fifth 。

This is a local server command example:

这是一个本地服务器命令示例：

• ssh root@your_server_ip

  ssh root @ your_server_ip

These are non-primary server command examples, useful for multi-server setups:

这些是非主要服务器命令示例，对于多服务器设置非常有用：

• echo "Secondary server"
  回显“辅助服务器”

• echo "Third server"
  回显“第三台服务器”

• echo "Fourth server"
  回显“第四台服务器”

• echo "Fifth server
  回声“第五台服务器

注意和警告 (Notes and Warnings)

The DigitalOcean Markdown parser allows for custom note and warning code blocks to be used to display very important text.

DigitalOcean Markdown解析器允许使用自定义注释和警告代码块来显示非常重要的文本。

Here’s a Markdown example of a note and a warning (this is an image):

这是注释和警告的Markdown示例(这是图片)：

Here’s the rendered result:

这是渲染的结果：

Note: This is a note.

注意：这是一个注意事项。

Warning: This is a warning.

警告：这是警告。

变数 (Variables)

Highlight any items that need to be changed by the reader, like example URLs or modified lines in configuration files. You can do this by surrounding the word or line with our custom <^> Markdown. Note that you cannot highlight multiple lines with one pair of symbols, so you need to highlight each line individually.

突出显示读者需要更改的所有项目，例如示例URL或配置文件中的修改行。 您可以通过使用自定义的<^> Markdown围绕单词或行来做到这一点。 请注意，您不能用一对符号突出显示多行，因此需要分别突出显示每行。

If you reference a variable in a context where you would normally also use in-line code formatting, you should use 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”.

如果在通常也使用in-line code格式的上下文中引用变量，则应同时使用both styles 。 通过使用“在前面的代码块中突出显示”而不是“上方红色突出显示”之类的语言，确保您的教程尽可能易于访问。

Avoid language like “highlighted in red below”

避免使用“下面以红色突出显示”之类的语言

图片和其他资产 (Images and Other Assets)

Images can quickly illustrate a point or provide additional clarification in a step. Use images for screenshots of GUIs, interactive dialogue, and diagrams of server setups. Don’t use images for screenshots of code, configuration files, output, or anything that can be copied and pasted into the article.

图像可以快速说明一个要点，或在一个步骤中提供其他说明。 使用图像获取GUI的屏幕截图，交互式对话和服务器设置图。 不要将图像用作代码，配置文件，输出或任何可复制并粘贴到文章中的屏幕快照。

If you’re including images in your tutorial, please follow these guidelines:

如果您要在教程中包含图片，请遵循以下准则：

• Include descriptive alt text so readers using a screen reader can rely on the alt text rather than the image.
  包括描述性替代文本，以便使用屏幕阅读器的阅读器可以依赖替代文本而不是图像。

• Use the .png file format

  使用.png文件格式

• Host images on imgur

  在imgur上托管图片

• Make the image with as short a height as possible
  使图像高度尽可能短

If you make a mockup of a diagram for your tutorial, we will create a diagram in the DigitalOcean style. We’ll also upload all images to DigitalOcean servers at publication time.

如果您为教程制作图表的模型，我们将以DigitalOcean样式创建一个图表。 我们还将在发布时将所有图像上传到DigitalOcean服务器。

Here’s a Markdown example for including images in your tutorial:

这是一个Markdown示例，用于在教程中包含图像：

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

Occasionally, you will want the reader to have access to a configuration file that is too long to display in the main body of the tutorial. DigitalOcean will host this file on our assets server. You can use standard link formatting to link to the file.

有时，您会希望读者可以访问一个配置文件，该配置文件太长而无法显示在教程的主体中。 DigitalOcean将在我们的资产服务器上托管此文件。 您可以使用标准链接格式链接到文件。

术语 (Terminology)

用户，主机名和域 (Users, Hostnames, and Domains)

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

我们的默认示例用户名是sammy 。 您也可以选择有用的描述性内容，例如webdav-kai或nsd 。

your_server is the default hostname, though you are encouraged to choose something descriptive, especially in multi-server setups, like django_replica_1.

尽管建议您选择描述性的名称，但your_server是默认的主机名，尤其是在多服务器设置中，例如django_replica_1 。

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

your_domain是默认域。 对于多服务器设置，您可以选择诸如primary-1.your_domain或plicate -1.your_domain之 类的东西 。 尽管example.com是文档的有效域，但在教程中使用your_domain可以使读者更清楚地了解示例中的域。

Use highlighting when using these in configuration files, like this:

在配置文件中使用它们时，请使用突出显示，如下所示：

example configuration file

示例配置文件

ip: your_server_ip
domain: primary-1.your_domain

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

这使读者很清楚，他们应该进行一些更改。

IP地址和URL (IP Addresses and URLs)

your_server_ip, with in-line code formatting and variable highlighting, is the default way to show an IP address. You can show multiple IP addresses with names like primary_private_ip and replica_private_ip. If you need to illustrate more realistic IP addresses, use an address in the one of the two blocks reserved for documentation as per RFC-5737. Specifically, we recommend 203.0.113.0/24 for example public addresses and 198.51.100.0/24 for example private addresses.

使用内联代码格式和突出显示变量的your_server_ip是显示IP地址的默认方式。 您可以显示多个IP地址，名称为primary_private_ip和replica_private_ip 。 如果需要说明更实际的IP地址，请按照RFC-5737在保留用于文档的两个模块之一中使用一个地址。 具体来说，我们建议使用203.0.113.0/24 (例如公共地址)和198.51.100.0/24 (例如专用地址)。

Example URLs that contain a variable the reader needs to customize should use code formatting with the variable highlighted. We default to using your_domain. like https://your_domain:3000/simple/ or http://your_server_ip/. However, live links should instead use the standard Markdown link style with no extra formatting.

包含读者需要自定义的变量的示例URL应使用代码格式，突出显示该变量。 我们默认使用your_domain 。 例如https:// your_domain :3000/simple/或http:// your_server_ip / 。 但是，实时链接应改用标准的Markdown链接样式，而无需额外的格式。

软件 (Software)

Use the official website’s capitalization of the name of their software. If the product website is not consistent with their capitalization, just be consistent within a single article.

使用官方网站上其软件名称的大写字母。 如果产品网站与其大小写不一致，则只需在一篇文章中保持一致即可。

Link to the software’s home page when you first mention the software.

首次提及该软件时，请链接到该软件的主页。

多服务器设置 (Multi-server Setups)

For technical clarity, use the project’s terminology for multi-server setups. Please be clear that the terms are coming from the project. For example: “The Django project refers to the original server as the primary and the secondary server as the replica. The MySQL project refers to the original server as the master and the secondary server as the slave.”

为了技术清晰起见，请使用项目的术语进行多服务器设置。 请清楚，这些条款来自该项目。 例如：“ Django项目将原始服务器称为主要服务器，将辅助服务器称为副本服务器。 MySQL项目将原始服务器称为主服务器，将辅助服务器称为从服务器。”

When discussing multi-server architectures more abstractly, use the terms primary and replica or manager and worker.

在更抽象地讨论多服务器体系结构时，请使用术语primary和副本或manager和worker 。

技术最佳实践 (Technical Best Practices)

Our technical best practices guide guide contains more guidance that will help you create consistent, quality tutorials that help our readers.

我们的技术最佳实践指南指南包含更多指南，这些指南将帮助您创建一致的高质量教程，以帮助我们的读者。

Follow this link to become a DigitalOcean author.

单击此链接成为DigitalOcean作者 。

翻译自: https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines