Silicon Cloud的技术写作准则

Silicon Cloud很兴奋地继续扩大其与服务器管理和软件工程相关的技术文章集合。为了确保Silicon Cloud文章在质量和风格上保持一致,我们制定了以下准则。

这个指南分为四个部分。

  • Style, our high-level approach to writing technical tutorials
  • Structure, an explanation of our layout and content
  • Formatting, a Markdown reference guide
  • Terminology, a guide to common terms and word usage

为了尽快发表文章,我们建议您在开始写作之前先完整阅读《风格和结构》部分。

在写作文章时,您可以使用本指南的格式部分以及我们的Markdown预览器和《如何撰写Silicon Cloud社区教程的提案和大纲》作为参考。

我们还有一份技术最佳实践指南,详细列出了我们针对技术的推荐建议。

Note

我们已经开发了Markdown格式的文章模板,您可以将其作为撰写文章的起点。我们强烈建议您使用其中的一个模板来规划和开发您的文章。

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


风格

数字海洋文章的风格体现了我们发布它们的目的:为工程师和开发者提供高质量的学习信息。我们努力确保所有数字海洋的教程都是:

  • Comprehensive and written for all experience levels
  • Technically detailed and correct
  • Practical, useful, and self-contained
  • Friendly but formal

这些原则指导作者创作文章、教程和其他学习材料,以帮助人们解决问题并成为更优秀的开发者。

全面而适合所有经验水平的写作

我们写的文章尽可能清晰和详细,而不假设读者有背景知识。

我们明确列出了每个读者需要使用一个全新服务器进行SSH连接的所有命令,直到最终完成工作设置。我们还提供了所有解释和背景信息,以帮助读者理解本教程。我们的目标是让读者学习概念,而不仅仅是复制粘贴代码和命令。

我们避免使用”简单”, “直接”,”容易”,”仅仅”,”显然”和”只是”等词语,因为这些词语对读者的知识做出了假设。尽管作者使用这些词语来鼓励读者克服困难的主题,但通常会产生相反的效果;当读者听说某事”容易”时,当他们遇到问题时就会感到沮丧。相反,我们通过提供他们成功所需的解释来鼓励我们的读者。

技术上详细且正确

我们的文章在技术上准确,并遵循行业最佳实践。它们不仅提供代码和指令,还提供更多细节。我们不会提供大量的配置或程序代码,并要求读者将其粘贴到文本编辑器中,相信它能够正常运行且安全可靠。我们提供所有读者所需要的细节,以便他们理解并信任文章。

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

作者们通过按照编写时的指导一字不差地在全新的服务器上实际操作来测试他们的教程,以确保准确性并发现遗漏的步骤。作为审查过程的一部分,我们的编辑们也会测试这些文章,以确保读者获得良好的学习体验。

实用的,有用的,独立完整的。

读者在完成一篇Silicon Cloud的文章后,他们将会从头到尾安装、构建或设置某个东西。我们强调实践性的方法:在一篇文章的结束处,读者应该拥有一个可用的环境或者一个可以进一步构建的示例。

对于作者来说,这意味着文章应该全面涵盖主题。作者应该在教程开始之前将已有的Silicon Cloud文章作为先决条件链接给读者,并在教程正文中提供额外的Silicon Cloud文章以提供更多的信息。只有在没有现有的Silicon Cloud文章且无法在文章中简要附加信息的情况下,作者才应该引导读者离开网页以获取信息。

友好而正式

我们的教程旨在采用友好但正式的语气。这意味着文章不包含行话、模因、过度的俚语、表情符号或笑话。因为我们的读者涵盖全球各地,所以我们的语气力求跨越语言和文化的界限。

与博客文章不同,我们不使用第一人称单数(例如,“我认为…”)。相反,我们鼓励使用第二人称(例如,“你将配置…”)来将焦点放在读者和他们将要完成的事情上。在某些情况下,我们会使用第一人称复数(例如,“我们将检查…”)。

我们鼓励以结果为重点的激励语言。例如,不要说“你将学会如何安装Apache”,而可以说“在这个教程中,你将安装Apache。”这种方法能激励读者,并关注他们需要完成的目标。

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


结构

Silicon Cloud的文章结构一致,包括引言、结论以及读者开始所需的先决条件。然而,具体的结构取决于文章的类型。

我们发布的大多数教程都是按照步骤逐步指导读者完成任务的程序性教程。程序性文章的结构应该是:

  • Title (Level 1 heading)
  • Introduction (Level 3 heading)
  • Prerequisites (Level 2 heading)
  • Step 1 — Doing the First Thing (Level 2 heading)
  • Step 2 — Doing the Next Thing (Level 2 heading)
  • Step n — Doing the Last Thing (Level 2 heading)
  • Conclusion (Level 2 heading)

概念性文章会有标题、引言和结论部分,但可能没有先决要求部分或遵循“步骤”约定。

  • Title (Level 1 heading)
  • Introduction (Level 3 heading)
  • Prerequisites (optional) (Level 2 heading)
  • Subtopic 1 (Level 2 heading)
  • Subtopic 2 (Level 2 heading)
  • Subtopic n (Level 2 heading)
  • Conclusion (Level 2 heading)

有些文章更关注于一个非常小的具体任务或解决方案,并且它们通常会有一个标题,一个简短的引言句子,以及一个结论。这些文章的结构通常如下:

  • Title (Level 1 heading)
  • Introduction paragraph
  • Prerequisites (optional) (Level 2 heading)
  • Article body
  • Conclusion paragraph

我们的文章模板已经为您在Markdown中编写了这个结构,并且我们鼓励您使用这些模板作为自己的文章的起点。

标题

当你编写标题时,请认真考虑读者通过遵循你的教程能够实现什么目标。尽量在标题中体现教程的目标,而不仅仅是读者用来实现目标的工具。最理想的情况是标题不超过60个字符。

一个典型的过程教程标题遵循以下格式:如何在<发行版>上使用<软件>完成<任务>。

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

具有目标的标题(如“如何在Ubuntu 22.04上使用Cloudflare和Nginx托管网站”)通常比没有目标的标题(如“如何在Ubuntu 22.04上使用Cloudflare和Nginx”)对读者更具信息性。

引言

每篇文章的第一部分是引言,通常包含一到三段。引言的目的是激发读者的兴趣、设立期望,并概述读者将在文章中了解到的内容。你的引言应该回答以下问题:

  • 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?

在你的引言中回答这些问题还将有助于你设计一个清晰、以读者为中心的教程,因为你将根据引言中提到的内容对教程的内容进行调整。一个好的引言可以让学习者知道文章的其余部分是关于什么的。

将注意力集中在读者身上,关注他们将会取得的成就。不要使用诸如“我们将学习如何”这样的短语,而是使用类似“您将配置”或“您将构建”的短语。这将极大地激励读者,让他们对你的主题感到兴奋。此外,将焦点放在读者解决的问题上,而不是技术本身。例如,如果一个教程是关于使用React构建一个项目,你可以将介绍集中在项目上,而不是解释React是什么。

先决条件

Silicon Cloud文章的前提条件部分有一个非常特定的格式和目的。

目的是明确告诉读者在按照当前的教程之前应该拥有或做到什么。格式是一个读者可以用作清单的列表。每一点必须链接到现有的Silicon Cloud教程,以涵盖必要的内容;如果没有当前的Silicon Cloud教程,可以链接到官方产品文档。这样你就可以依赖已知可行的现有内容,而不是从头开始。

我们的系统和DevOps教程将读者从一个新部署的基本分发镜像一直引导到一个可工作的设置,因此它们应当从第一个SSH连接到服务器开始,或者包括一个先决条件教程。

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

  • 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).
  • Software installation and configuration, such as Apache, a LAMP stack, or databases.
  • Required DNS settings or SSL certificates.

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

软件开发教程的普遍前提条件包括:

  • Local software needed, such as Git, Node.js, Python, Ruby, or Docker.
  • Additional user accounts like GitHub, Facebook, Twitter, or other services your reader will need.
  • Tutorials that will help the reader get their project started, such as or How To Set Up an HTML Project.
  • Conceptual articles that provide important background a reader might find helpful, such as Understanding the DOM.

例如,关于使用Git构建和部署Node.js应用程序到Ubuntu服务器的教程可能有以下先决条件:

完成本教程,您需要以下内容:

一个按照Ubuntu 22.04初始服务器设置指南设置的Ubuntu 22.04服务器,包括一个非根的sudo-enabled用户和防火墙。
一个配置指向您的服务器的域名。您可以按照域名和DNS指南了解如何将域名指向Silicon Cloud vServers。
在您的本地机器上安装Git。您可以按照参与开源项目:使用Git入门教程在您的计算机上安装并设置Git。
一个本地Node.js开发环境,您可以按照如何在Ubuntu 22.04上安装Node.js教程进行设置。对于其他系统,请按照适当的教程为您的系统安装Node.js并创建本地开发环境。

通过阅读先决条件,您的读者清楚地知道在开始之前需要做什么。没有任何意外。

当你测试教程时,请按照先决教程的要求准确操作,这样每个人都能以相同的起点开始。如果你更改了变量或完成了先决教程中的可选步骤,请确保做出相应注明。

您可以查看一些优秀的先决条件示例来进行参考。

  • Ubuntu 20.04 servers, software installation, and DNS records in this Minio tutorial’s prerequisites.
  • Handling multiple servers with software installation in this monitoring tutorial’s prerequisites or this Nagios and Alerta tutorial’s prerequisites.
  • React-based web development projects by reading How To Test a React App with Jest and React Testing Library.

对您的先决条件要具体明确。像“熟悉JavaScript”这样的先决条件如果没有具体链接,不会给读者提供太多上下文。相反地,列出读者应该了解的具体概念,并为他们提供帮助他们迅速掌握这些概念的资源,以便他们能成功完成您的教程。例如,可以使用类似于“熟悉JavaScript。要提升您的技能,请查看《JavaScript编码入门系列》”。

步骤

教程的步骤部分是你描述读者需要做什么以及为什么需要这样做的部分。每一步包括命令、代码清单和文件,并提供解释,不仅解释了如何做,还解释了为什么要以这种方式做。

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

逐步教程以“步骤”和数字开头,紧接着是一个长破折号。每个步骤标题描述了读者在该步骤中会完成的内容,并使用动名词形式(以-ing结尾的单词)。

步骤1 – 创建用户账户

在标题之后,加上一个介绍性的句子,描述读者在每个步骤中要做什么,以及它在实现教程的整体目标中扮演的角色。侧重于读者。使用“你将建立”或“你将创建”等短语,而不是“我们将学习”或“我将解释”的短语。

逐步执行的指令

所有读者必须运行的命令应该独占一行,它们应该在自己的代码块中,并且每个命令前应该有一个描述来解释命令的功能。命令之后,提供关于命令的附加详细信息,例如参数的作用以及读者为什么使用它们。

执行以下命令以显示/home/sammy目录的内容,包括所有隐藏文件:
ls -al /home/sammy

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

你应该使用单独的代码块显示命令和程序的输出,例如下面的例子:

运行 hello.js 程序:
node hello.js

程序的输出将打印到屏幕上:
输出 你好,世界!
这是我的第一个 Node.js 程序!

输出块拥有一个标签,并且用一些解释性文本与命令部分分隔开来。将命令部分与输出部分分开,可以使读者更清晰地辨别出命令的结束位置和输出的开始位置。

如果读者需要在目录之间切换,请确保提供切换所需的命令。

打开、创建和查看文件

就像命令一样,总是通过描述文件或脚本的总体目的来引入它,然后解释读者将在文件中进行的任何更改。没有这些解释,读者将无法自定义、更新或解决问题。

明确告诉用户创建或打开每个他们需要使用的文件。

在面向命令行用户的教程中,指导读者使用独立的命令行来创建并打开文件。

使用以下命令打开文件/etc/hginx/config:
nano /etc/nginx/sites-available/default

Note

我们在Ubuntu和Debian的教程中使用nano编辑器,因为它已经安装好了。而在CentOS和FreeBSD的教程中,我们使用vi。在所有情况下,避免使用touch命令创建空文件,因为读者可以直接使用编辑器创建文件。

对于那些读者不需要使用命令行界面的教程(比如前端开发教程),可以省略打开文件的命令。然而,一定要明确告诉读者要打开哪个文件。

在你的编辑器中打开文件 src/App.js。

一个读者应该始终知道他们正在处理的文件是哪个。

代碼塊

我们把所有的代码看作是学习的机会。如果你要求读者编写代码,采用和命令一样的方式:先介绍代码块的高级解释,然后展示代码,最后指出任何重要的细节。

这里有一个例子:

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

将以下代码添加到文件中,代码会在屏幕上打印一条消息:
hello.js
console.log(“你好世界!”);
console.log(“这是我的第一个Node.js程序!”)

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;

}

请确保解释该变更的目的和必要性。

Silicon Cloud为了使我们的教程指南更易于阅读,设计了自定义的Markdown和格式设置指南。

过渡

每个步骤都应该附有一个简短的引言句和一个总结过渡句,描述读者完成了什么以及接下来的目标。过渡句引导读者,并为说明、命令和输出提供重要背景。为避免重复,用不同的语言编写这些句子,以免再次重申步骤标题。

这是一个例子,在Rocky Linux 8上的“How To Secure Nginx with Let’s Encrypt”教程中,展示了在第一步结束时的过渡。

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

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

以这种方式构建每一步帮助读者学习并激励他们继续前进。

结论

通过您的教程,读者所完成的内容应该在结论中进行总结。不要使用”我们学会了如何”这样的短语,而是使用”您进行了配置”或”您进行了构建”这样的短语。

结论还应描述读者下一步可以做什么,包括对用例或功能的描述,读者可以探索链接到其他Silicon Cloud教程的链接以进行额外设置或配置以及外部文档的链接。

一些好的例子包括这个Kubernetes教程的结论和这个node-csv教程的结论。


排版

数字海洋的教程是以Markdown标记语言格式化的。如果你对此不熟悉,Daring Fireball出版了一本全面的Markdown指南。数字海洋还使用了一些自定义Markdown。我们的自定义Markdown示例在下面的适当部分中。

标题

我们的教程的每个部分都有相应的标题:标题应该是一级标题;介绍应该是三级标题;先决条件、步骤和结论应该有二级标题。你可以在我们的 Markdown 文章模板中查看这种格式。

对于程序教程,步骤标题应该包括步骤编号(数字)后面跟一个破折号(—)。

步骤标题也应使用动名词,即”-ing”结尾的词语。一个示例的步骤标题是第一步 – 安装Nginx。

请谨慎使用H3标题,避免使用H4标题。如果需要使用子标题,请确保在教程的该部分有两个或更多级别的标题。或者,考虑拆分成多个步骤。

行级格式化 jí

粗体文字应该用来:

  • Visible GUI text
  • Hostnames and usernames, like wordpress-1 or sammy
  • Term lists
  • Emphasis when changing context for a command, like switching to a new server or user

只有在介绍技术术语时才应使用斜体字。例如,Nginx服务器将作为我们的负载均衡器。

内联代码格式应用于:

  • Command names, like unzip
  • Package names, like mysql-server
  • Optional commands
  • File names and paths, like ~/.ssh/authorized_keys
  • Example URLs, like http://your_domain
  • Ports, like :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.

代码块

代码块应该用于:

  • Commands the reader needs to execute to complete the tutorial
  • Files and scripts
  • Terminal output
  • Interactive dialogues that are in text

在文件中使用省略号(. . .)标注摘录和省略部分。如果读者需要进行任何修改,请使用高亮标示。

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

}

如果文件的大部分内容都可以使用默认设置,我们通常只显示需要更改的部分。

如果读者正在向预先存在的代码中添加行,可以使用高亮来标示新添加的行或其他更改。以下是教程《如何使用Go模块》中的一个示例。

打开mymodule目录下的main.go文件,并添加一个调用PrintHello函数的语句,具体添加方式如下所示:
projects/mymodule/main.go

package main

import (
“fmt”

“mymodule/mypackage”
)

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

mypackage.PrintHello()
}

在上面的例子中,读者将添加的项目都被突出显示。

代码块前缀

在代码块中不要包含命令提示符($或#)。而是分别使用Silicon Cloud的自定义Markdown来表示非root用户命令、root用户命令和自定义前缀。

```command
sudo apt update
```

```super_user
adduser sammy
```

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

以下是先前的例子的展示结果:

sudo apt update
更新sudo apt

adduser sammy
添加用户sammy

FLUSH PRIVILEGES;
刷新权限。

当您以这种方式呈现指令时,读者将无法无意中选择提示字符。

代码块标签

Silicon Cloud的Markdown还包括标签和次级标签。您可以通过在代码块中的任意位置添加一行文本 [label 标签文本] 或 [secondary_label 次级标签文本] 来为代码块添加标签。

使用标签来标记包含文件内容的代码块,并附上文件名。例如,如果有一个名为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!

标签有助于读者理解他们正在阅读的内容以及它如何与整体情境相呼应。

代码块环境颜色

有时候读者需要在多台计算机上工作,比如本地计算机和多个服务器上。使用不同颜色来显示环境可以让读者更容易跟踪。Silicon Cloud的Markdown允许你通过在代码块中的任何位置添加一行[环境名称]来为代码块的背景添加颜色。名称的选项有本地,第二,第三,第四和第五。

例如,如果您正在撰写一个教程,并且希望展示一个应该在本地而不是服务器上运行的命令,您可以使用[环境 local]:

以本机IP为参数,使用root账户通过SSH连接到服务器。

这些是非主服务器命令示例,适用于多服务器设置。

使用[环境第二]会呈现如下:

  1. echo "Secondary server"

使用[环境三]将呈现如下:

  1. echo "Third server"

使用“环境第四”将呈现如下:

  1. echo "Fourth server"

然后【第五环境】会显示为这样:

  1. echo "Fifth server

在多服务器或多环境教程中使用这些颜色。在必要时,您可以堆叠一个环境标签和一个输出标签来指示位于不同环境中的文件,例如在本地环境中的示例输出块。

输出你好世界!

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

注意事项和警告

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

这是一个Markdown示例,显示了一个注释和一个警告(这是一张图片)。

Notes and Warnings

这是渲染的结果:

Note

注意:这是一张便条。

Warning

警告:这是一个警告。

关于Silicon Cloud的特定信息

当讨论Silicon Cloud特定功能时,[info]提示框非常有用。

Info

这个特性只适用于Silicon Cloud的vServers。

变量

高亮读者需要修改的项,如示例URL、版本号或配置文件中的修改行。您可以通过在单词或行前后使用我们自定义的<^> Markdown来实现这一点。

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

这个例子创建了一个名为sammy的新用户,但你应该用你喜欢的用户名替换它:
添加用户 sammy。

Note

注意:您不能使用一对符号同时突出显示多行,因此需要逐行突出显示。偶尔,像井号(#)或反引号这样的符号可能会中断行的突出显示功能,可能需要在同一行上有两个突出显示的部分。

如果您在通常需要使用内联代码格式的上下文中引用一个变量,您应该同时使用两种样式。确保您的教程尽可能易于理解,可以使用“在前面的代码块中突出显示”这样的语言,而不是“在上面以红色突出显示”。

避免使用类似“以黄色标记”之类的语言,因为标记的颜色可能会发生变化。

图片和其他资源

图片可以迅速说明一点或在步骤中提供额外的澄清。使用图片来截取图形用户界面、交互式对话框和服务器设置图表。不要使用图片来截取代码、配置文件、输出或任何可以复制粘贴到文章中的内容。

在编写教程时,若需要插入图片,请按照以下准则操作:

  • Include descriptive alt text so readers using a screen reader can rely on the alt text rather than the image.
  • Include a brief caption to contextualize the image within the context of the article (the caption will typically be shorter than alt text).
  • Use the .png file format.
  • Host images on imgur.
  • Make the image with as short a height as possible.

如果您为教程制作了一个图表的模型,我们将按照Silicon Cloud的风格创建图表。我们还将在发布时将所有图片上传到Silicon Cloud的服务器中。

这是一个在你的教程中包含图片的Markdown示例。

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

您可以在这个Matomo教程的图片中查看优秀的描述性替代文字的示例。

有时候,你希望读者能够访问一个在教程的主体部分中无法显示完整的配置文件。Silicon Cloud将会在我们的资产服务器上托管这个文件。你可以使用标准的链接格式来链接到该文件。

术语

技术文章和教程会使用大量的术语,我们已经对一些术语和词语的使用进行了标准化。

用户、主机名和域名

我们的默认示例用户名是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

你的服务器IP以内联代码格式和变量高亮显示,是显示IP地址的默认方式。你可以使用primary_private_ip和replica_private_ip等带有名称的方式显示多个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项目将原始服务器称为主服务器,将次级服务器称为从服务器。”

当更抽象地讨论多服务器架构时,可以使用”主服务器和副本”或”管理服务器和工作服务器”这些术语。

技术最佳实践

我们的技术最佳实践指南中包含了更多的指导,这将帮助你创建一致、高质量的教程,以帮助我们的读者。

点击此链接成为Silicon Cloud的作家。

发表回复 0

Your email address will not be published. Required fields are marked *