DigitalOcean的技术写作指南

DebugUsery
403 阅读24分钟

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

本指南有四个部分。

  • 风格，我们编写技术教程的高级方法
  • 结构，对我们的布局和内容的解释
  • 格式，一个Markdown参考指南
  • 术语，常用术语和词汇使用指南

风格

DigitalOcean文章的风格反映了我们发布文章的目的：为工程师和开发人员提供高质量的学习信息。我们努力确保所有DigitalOcean的教程是。

  • 全面，为所有经验水平编写
  • 技术上详细和正确
  • 实用、有用、自成体系
  • 友好而正式

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

全面，为所有经验水平而写

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

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

我们避免使用 "简单"、"直截了当"、"容易"、"简单"、"明显 "和 "只是 "等词语，因为这些词语会对读者的知识做出假设。虽然作者用这些词来鼓励和激励读者去推动具有挑战性的话题，但它们往往会产生相反的效果；当读者听到某件事情 "很容易 "时，他们可能会在遇到问题时感到沮丧。相反，我们通过提供他们成功所需的解释来鼓励我们的读者。

技术上的详细和正确

我们的文章在技术上是准确的，并遵循行业的最佳实践。他们还提供更多的细节，而不仅仅是代码和命令。我们不提供大块的配置或程序代码，并要求读者将其粘贴到他们的文本编辑器中，相信我们的工作和安全。我们提供所有必要的细节，以使读者理解和信任这篇文章。

每条命令都应该有一个详细的解释，包括必要的选项和标志。每一个代码块后面都应该有散文解释，描述它的作用和为什么这样工作。当你要求读者执行一个命令或修改一个配置文件时，首先要解释它是做什么的，以及为什么你要求读者做这些修改。这些细节为读者提供了他们需要的信息，以增长他们的技能。

作者对他们的教程进行测试，以确保他们在新的服务器上完全按照所写的内容进行操作，以确保准确性并找出遗漏的步骤。我们的编辑也对这些文章进行测试，作为审查过程的一部分，以确保为读者提供良好的学习体验。

实用、有用、自成一体

一旦读者完成了DigitalOcean的文章，他们将从头到尾安装、构建或设置一些东西。我们强调实用的方法：在文章的最后，读者应该有一个可用的环境或一个例子来建立。

这对作者来说意味着，文章应彻底涵盖该主题。作者应链接到现有的DigitalOcean文章，作为读者在开始教程前的先决条件，并链接到现有的DigitalOcean文章，在教程正文中提供额外的信息。如果没有现有的DigitalOcean文章，而且信息不能直接添加到文章的简短摘要中，作者只应让读者到网站外收集信息。

友好而正式

我们的教程以友好但正式的语气为目标。这意味着，文章不包括行话、备忘录、过度的俚语、表情符号或笑话。由于我们是为全球受众编写的，我们的目标是使语气跨越语言和文化的界限。

与博客文章不同，我们不使用第一人称单数（例如，"我认为......"）。相反，我们鼓励使用第二人称（例如，"你将配置......"），以便将重点放在读者和他们将完成的任务上。在某些情况下，我们会使用第一人称复数（例如，"我们将检查..."）。

我们鼓励注重结果的激励性语言。例如，不使用 "你将学会如何安装Apache"，而使用 "在本教程中，你将安装Apache"。这种方法可以激励读者，并将重点放在他们需要完成的目标上。

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

结构

DigitalOcean的文章有一个一致的结构，其中包括一个介绍，一个结论，以及任何必要的前提条件，让读者开始。然而，具体的结构取决于文章的类型。

我们发布的大多数教程都是程序性的，它引导读者一步步完成一项任务。程序性文章的结构是这样的。

  • 标题（第1级标题）
  • 介绍（第3级标题）
  • 先决条件（第2级标题）
  • 第1步--做第一件事（第2级标题）
  • 第2步--做下一件事（第2级标题）
  • ...
  • 第n步--做最后一件事（第2级标题）
  • 结论（第2级标题）

概念性文章会有一个标题、一个介绍和一个结论，但它们可能没有先决条件部分或遵循 "步骤 "惯例。

  • 标题（第1级标题）
  • 介绍（第3级标题）
  • 先决条件（可选）（第2级标题）
  • 副题1（第2级标题）
  • 副题2（第2级标题）
  • ...
  • 小标题n (第2层标题)
  • 结论 (第2级标题)

有些文章更专注于一个非常小的具体任务或解决方案，它们通常会有一个标题，一个小的介绍性句子，以及最后的结论。这些文章的结构会是这样的。

  • 标题（第1级标题）
  • 介绍段落
  • 前提条件（可选）（第2级标题）
  • 文章主体
  • 结语段

标题

当你写你的标题时，仔细考虑一下读者跟着你的教程会完成什么。尽量在标题中包括教程的目标，而不仅仅是读者将使用的工具来完成这一目标。理想情况下，标题的长度应在60个字符以下。

一个典型的程序性教程的标题是这样的格式。如何在上用完成一项任务。

例如，如果你的教程是关于安装Caddy网络服务器，目标可能是托管一个网站。如果你的教程是关于安装Fail2Ban，目标可能是保护一个Nginx服务器。

包含目标的标题（如 "如何在Ubuntu 22.04上使用Cloudflare和Nginx托管网站"）通常比不包含目标的标题（如 "如何在Ubuntu 22.04上使用Cloudflare和Nginx"）更能为读者提供信息。

简介

每篇文章的第一部分是导论，通常有一到三段。引言的目的是激励读者，设定期望，并总结读者在文章中要做的事情。你的导言应该回答以下问题。

  • 该教程是关于什么的？涉及哪些软件，每个组件的作用是什么（简要介绍）？
  • 读者为什么要学习这个主题？在这种配置下使用这种特定软件有什么好处？读者应该遵循本教程的一些实际原因是什么？
  • 读者在本教程中会做什么或创建什么？他们是要建立一个服务器，然后进行测试吗？他们是在建立一个应用程序并进行部署吗？要具体，因为这能提供读者所需的动力，让他们对这个主题感到兴奋。
  • 读者在完成后会有什么成就？他们会有什么新技能？他们将能做什么以前做不到的事？

在介绍中回答这些问题，也将有助于你设计一个清晰的、以读者为中心的教程，因为你将把教程的内容与你在介绍中提到的东西统一起来。一个好的导语能让学习者知道文章的其余部分是什么。

把重点放在读者身上，以及他们将完成什么。不要使用 "我们将学习如何 "这样的短语，而要使用 "你将配置 "或 "你将构建 "这样的短语。 这在很大程度上可以激励读者，使他们对你的主题感到兴奋。此外，将重点放在读者要解决的问题上，而不是技术上。例如，如果一个教程是关于用React构建一个项目，你可以把介绍的重点放在项目上，而不是解释React是什么。

前提条件

DigitalOcean文章的先决条件部分有一个非常具体的格式和目的。

其目的是准确地说明读者在跟随当前教程之前应该具备或做什么。其格式是一个列表，读者可以将其作为一个检查清单。每一点都必须链接到涵盖必要内容的现有DigitalOcean教程，如果没有现有DigitalOcean教程，则链接到官方产品文档。这使您能够依靠已知的现有内容，而不是从头开始。

我们的系统和DevOps教程将读者从一个新的部署的vanilla分布图像到一个工作的设置，所以他们应该从第一个SSH连接到服务器开始，或包括一个先决条件的教程。

系统管理和DevOps教程的常见先决条件包括。

  • 必要的服务器数量，包括分布、初始服务器设置和任何额外的必要选项（如内存要求、DO API密钥、IPv6或私人网络）。
  • 软件安装和配置，如Apache、LAMP栈或数据库。
  • 所需的DNS设置或SSL证书。

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

软件开发教程的常见先决条件包括。

  • 需要的本地软件，如Git、Node.js、Python、Ruby或Docker。
  • 额外的用户账户，如GitHub、Facebook、Twitter或其他你的读者需要的服务。
  • 帮助读者开始项目的教程。
  • 提供重要背景的概念性文章，读者可能会觉得有帮助。

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

先决条件

通过阅读先决条件，你的读者在开始之前就清楚地知道他们需要做什么。不会有任何意外。

当你测试你的教程时，完全按照所有先决条件的教程来写，这样每个人都使用相同的起点。如果你改变了一个变量或完成了一个先决条件中的可选步骤，一定要注意这一点。

对你的先决条件要有针对性。像 "熟悉JavaScript "这样的先决条件，如果没有具体的链接，就不能给你的读者提供很多背景。相反，列出读者应该知道的具体概念，并为他们提供资源，帮助他们加速，以便他们能够成功地完成你的教程。例如，使用类似 "熟悉Javascript。

步骤

步骤部分是你的教程中描述读者需要做什么以及为什么要做的部分。一个步骤包含命令、代码列表和文件，并提供解释，不仅说明要做什么，还说明为什么要这样做。

每个步骤都以2级标题开始。

程序性教程的每个步骤标题都以 "步骤"和一个数字开始，后面是一个虚线。步骤标题描述读者在该步骤中要完成的任务，并使用动名词**（-ing**words），像这样。

第1步--创建用户账户

在标题之后，添加一个介绍性的句子，描述读者在每个步骤中要做什么，以及在实现教程的总体目标中起什么作用。把重点放在读者身上。不要使用 "我们将学习 "或 "我将解释 "这样的短语，而要使用 "你将构建 "或 "你将创建 "这样的短语。

命令的步骤

读者必须运行的所有命令都应该在自己的代码块中的自己的一行，每个命令前面都应该有一个说明，解释该命令的作用。在命令之后，提供关于该命令的额外细节，例如参数的作用以及为什么你的阅读器要使用它们。

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

ls -al /home/sammy

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

你应该用一个单独的代码块来显示命令和程序的输出，比如下面的例子。

运行hello.js 程序。

node hello.js

你会看到该程序的输出出现在屏幕上。

Output
Hello 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 函数接收一个字符串，并在自己的行上将其打印到屏幕上。

请注意，该代码块有一个标签，清楚地显示了文件名。

这个Docker Swarm教程是一个很好的例子，说明如何使用我们的自定义Markdown来区分在几个不同的服务器以及本地运行的命令。

有时你会打开一个文件，要求读者改变一些特定的东西。当你这样做的时候，要显示文件的相关部分，并使用高亮标记来明确应该改变什么。

在你的编辑器中打开文件/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;
...

}

请务必解释该变化的作用以及为什么它是必要的。

过渡

每个步骤都应该有一个简短的介绍性句子和一个结尾的过渡性句子，描述读者完成了什么，以及他们接下来要去哪里。过渡句引导读者，并为指令、命令和输出提供重要的背景。为了避免重复，要改变这些句子的语言，使其不重复步骤的标题。

下面是一个过渡的例子。

你现在已经安装了Let's Encrypt客户端，但在获得证书之前，你需要确保所有需要的端口都已打开。要做到这一点，你将在下一步更新你的防火墙设置。

在上面的例子中，作者总结了读者取得的成果，介绍了下一个任务，并解释了这两个步骤的联系。

以这种方式框定每个步骤有助于读者学习，并激励他们继续前进。

结论

教程的结论应该总结读者通过学习你的教程所取得的成果。不要使用 "我们学会了如何 "这样的短语，而要使用 "你配置了 "或 "你构建了 "这样的短语。

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

格式化

DigitalOcean的教程是以Markdown标记语言进行格式化的。如果你对Markdown不熟悉，Daring Fireball发布了一份全面的Markdown指南。DigitalOcean也使用一些自定义的Markdown。我们的自定义Markdown的例子在下面的适当部分。

页眉

我们的教程的每个部分都有一个相应的标题：标题应该是H1标题；介绍应该是H3标题；先决条件、步骤和结论应该有H2标题。

对于程序性教程来说，步骤标题应该包括步骤编号（数字），后面是一个破折号**（-）**。

步骤标题还应该使用动词，也就是**-ing词。一个步骤标题的例子是步骤1--安装Nginx**。

少用H3标题，避免使用H4标题。如果你需要使用副标题，确保在教程的该部分有两个或更多该级别的标题。另外，也可以考虑做多个步骤。

行级格式化

粗体字应该用于。

  • 可见的GUI文本
  • 主机名和用户名，如wordpress-1或sammy
  • 术语列表
  • 当改变一个命令的上下文时，如切换到一个新的服务器或用户时，要强调。

斜体字只应在介绍技术术语时使用。例如，Nginx服务器将是我们的负载平衡器。

内行代码格式应该用于。

  • 命令名称，如unzip
  • 包名称，如mysql-server
  • 可选命令
  • 文件名和路径，如~/.ssh/authorized_keys
  • 示例的URL，如 http://your_domain
  • 端口，如: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;
...

}

如果一个文件的大部分内容可以保留默认设置，我们通常只显示需要修改的部分。

如果读者在已有的代码中增加了几行，就用高亮显示新的几行或其他变化。

从mymodule 目录中打开你的main.go 文件，通过添加下面的高亮行来增加对PrintHello 的调用。

projects/mymodule/main.go

package main

import (
	"fmt"

	"mymodule/mypackage"
)

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

	mypackage.PrintHello()
}

在上面的例子中，读者要添加的项目都是高亮显示的。

代码块前缀

不要在代码块中包括命令提示 ($ 或#) 。相反，使用DigitalOcean的自定义Markdown，分别用于非root用户命令、root用户命令和自定义前缀。

```command
sudo apt update
```

```super_user
adduser sammy
```

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

这就是前面的例子在呈现时的样子。

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

二级标签看起来像这样。

Output
Hello 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

在多服务器或多环境的教程中使用这些颜色。在必要时，你可以将环境标签和输出标签堆叠起来，以表示不同环境中的文件，就像这个本地环境中的输出样本块。

Output
Hello World!

嵌套标签确保读者拥有所有必要的信息，以便在适当的终端会话中运行命令。

注释和警告

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

下面是一个关于注释和警告的Markdown例子（这是一张图片）。

Notes and Warnings

这里是渲染的结果。

注释：这是一个注释。

警告：这是一个警告。

DigitalOcean的具体信息

在讨论DigitalOcean的具体功能时，[info] 呼出是有帮助的。

这个功能是DigitalOcean的Droplets所特有的。

变量

突出显示读者需要改变的任何项目，如实例URL、版本号或配置文件中的修改行。你可以通过用我们自定义的**<^>**Markdown包围单词或行来做到这一点。

下面是一个来自Ubuntu 22.04的初始服务器设置的例子。

这个例子创建了一个叫sammy的新用户，但你应该用一个你喜欢的用户名来替换它。

adduser sammy

注意：你不能用一对符号突出多行，所以你需要单独突出每一行。偶尔一个符号如shebang (#)或backtick可能会破坏行中的高亮功能，你可能需要在同一行中有两个高亮部分。

如果你在一个通常也会使用in-line code 格式的环境中引用一个变量，你应该使用 both styles.通过使用 "在前面的代码块中突出显示 "而不是 "在上面用红色突出显示 "这样的语言，确保你的教程尽可能地易于理解。

避免使用 "以黄色突出显示 "这样的语言，因为突出显示的颜色可能会改变。

图片和其他资产

图片可以快速说明一个问题，或者在一个步骤中提供额外的说明。将图像用于图形用户界面的截图、交互式对话和服务器设置的图表。不要将图片用于代码、配置文件、输出或任何可以复制和粘贴到文章中的截图。

当在你的教程中包含图片时，请遵循这些准则。

  • 包括描述性的alt文本，以便使用屏幕阅读器的读者可以依靠alt文本而不是图片。
  • 包括一个简短的标题，以便在文章的上下文中说明图片的内容（标题通常比alt文本要短）。
  • 使用.png 文件格式。
  • 将图片放在imgur上。
  • 尽可能缩短图片的高度。

如果你为你的教程制作一个模拟的图表，我们将按照DigitalOcean的风格制作一个图表。我们也会在出版时将所有图片上传到DigitalOcean服务器。

这里有一个在教程中包含图片的Markdown例子。

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

偶尔，你会希望读者能够访问一个配置文件，该文件太长，无法在教程的主体部分显示。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地址的默认方式。你可以显示多个IP地址，名称为 primary_private_ip和 replica_private_ip.如果你需要说明更真实的IP地址，请使用根据RFC-5737为文档保留的两个块中的一个地址。具体来说，我们推荐203.0.113.0/24 ，用于说明公共地址，198.51.100.0/24 ，用于说明私人地址。

含有读者需要定制的变量的URL示例应该使用代码格式，并突出显示该变量。我们默认使用 your_domain，如 https://your_domain:3000/simple/或 http://your_server_ip/.然而，实时链接应该使用标准的Markdown链接风格，没有额外的格式化。

软件

使用官方网站对其软件名称的大写。如果产品网站与他们的大写字母不一致，在一篇文章中要保持一致。

当你第一次提到该软件时，要链接到该软件的主页。

多服务器设置

为了技术上的清晰，请使用项目的多服务器设置的术语。请明确这些术语来自该项目。比如说"Django项目将原始服务器称为主服务器，将辅助服务器称为副本。MySQL项目将原始服务器称为主服务器，将辅助服务器称为从服务器"。

当更抽象地讨论多服务器架构时，使用主服务器和副本或管理者和工作者的术语。

avatar
文章
阅读
粉丝