17. Style guide

17.1 Guidelines for authors

本节讨论在为live-manual编写技术文档时需要考虑的一些一般事项。它们分为语言特征和推荐程序。

注意:作者应先阅读Contributing to this document.

17.1.1 Linguistic features

记住，你的读者中有很大一部分不是以英语为母语的。所以作为一般规则，尽量使用简短而有意义的句子，后跟一个句号。

这并不意味着你必须使用简单、天真的风格。这是一个建议，尽量避免复杂的从属句，使文本对非英语母语者难以理解。

最广泛传播的英语变体是英式英语和美式英语，所以大多数作者很可能会使用其中之一。在协作的环境中，理想的变体是“国际英语”，但要在所有现有的变体中决定哪种变体是最好的，这是非常困难的，甚至是不可能的。

我们希望不同的品种可以混合在一起而不会产生误解，但总的来说，你应该尽量保持连贯，在决定使用英式、美式或任何其他英国风味之前，请看看其他人是如何写作的，并试着模仿他们。

不要有偏见。避免提及与实际操作完全无关的意识形态。技术写作应该尽可能保持中立。这是科学写作的本质。

尽量避免使用带有性别歧视的语言。如果你需要引用第三人称单数，最好使用“they”，而不是“he”或“she”或诸如“s/he”，“s(he)”之类的尴尬发明。

直入主题，不要漫无目的地闲逛。尽可能多地提供必要的信息，但不要提供多余的信息，也就是说，不要解释不必要的细节。你的读者很聪明。假定他们有一些先前的知识。

请记住，无论你写什么都必须被翻译成几种其他语言。这意味着如果您添加无用或冗余的信息，许多人将不得不做额外的工作。

如前所述，将协作文档标准化为一个完美统一的整体几乎是不可能的。然而，你所做的一切努力都将与其他作者保持一致。

使用尽可能多的文本形成手段，使你的文本连贯和明确。(文本形成设备是语言标记，如连接符)。

在一个或几个段落中描述要点比仅仅使用典型的“变更日志”风格的几个句子更可取。描述它!你的读者会喜欢的。

如果你不知道如何用英语表达某些概念，可以在字典或百科全书中查找单词的意思。但请记住，如果你不知道如何正确使用字典，它既可以成为你最好的朋友，也可以变成你最大的敌人。

英语拥有世界上最大的词汇量(超过一百万个单词)。这些词中有许多是从其他语言中借用来的。当在双语词典中查找单词的意思时，非英语母语人士倾向于选择在母语中听起来更相似的单词。这通常会变成一种过于正式的话语，在英语中听起来不太自然。

一般来说，如果一个概念可以用不同的同义词来表达，那么最好选择词典提出的第一个词。如果有疑问，选择日耳曼语起源的单词(通常是单音节单词)通常是正确的做法。请注意，这两种技巧可能会产生相当非正式的话语，但至少你选择的词语会被广泛使用并被普遍接受。

建议使用搭配字典。当你需要知道哪些单词通常会一起出现时，它们非常有帮助。

再一次，从别人的工作中学习是一个很好的实践。使用搜索引擎查看其他作者如何使用某些表达可能会有很大帮助。

提防虚伪的朋友。无论你多么精通一门外语，你都会时不时地落入所谓的“假朋友”的陷阱，这些词在两种语言中看起来很相似，但其含义或用法可能完全不同。

尽量避免使用习语。“习语”是一种表达方式，可能传达的意思与它们单独的单词所表达的意思完全不同。有时候，习语甚至对以英语为母语的人来说也很难理解!

尽管我们鼓励你使用普通的日常英语，但技术写作属于语言的正式范围。

尽量避免俚语、不寻常的、难以理解的缩写，尤其是那些试图模仿口语的缩写。更不用说典型的irc和家庭友好的表达。

17.1.2 Procedures

作者在将他们的示例添加到live-manual之前测试它们以确保一切都按照描述工作是很重要的。在干净的chroot或VM上进行测试是一个很好的起点。此外，最好在使用不同硬件的不同机器上进行测试，以发现可能出现的问题。

在提供示例时，尽可能具体。毕竟，一个例子只是一个例子。

通常，使用只适用于特定情况的一行比使用可能使读者感到困惑的抽象概念要好。在这种情况下，您可以简要说明所建议示例的效果。

当示例建议使用一些潜在的危险命令时，可能会有一些例外，如果滥用这些命令，可能会导致数据丢失或其他类似的不良影响。在这种情况下，你应该提供一个可能的副作用的详细解释。

只有当这些网站上的信息对理解一个特殊的观点至关重要时，才应该使用外部网站的链接。即便如此，尽量少使用外部站点的链接。互联网链接可能会不时改变，导致链接中断，使您的论点处于不完整状态。

此外，离线阅读手册的人将没有机会关注这些链接。

尽量避免打品牌。请记住，其他下游项目可能会使用您编写的文档。所以如果你加入某些特定的物质，就会使事情变得复杂。

live-manual是根据GNU GPL授权的。这对与它一起发布的材料(任何类型的，包括受版权保护的图形或徽标)的分发有许多影响。

使用传统的章节和字幕编号系统。例1、1.1、1.1.1、1.1.2……1.2, 1.2.1, 1.2.2…2,2.1…等等……见下面的标记。

如果你必须在描述中列举一系列步骤或阶段，你也可以使用序数:First, second, third…或者首先，然后，之后，最后……或者，您可以使用项目符号项。

最后但并非最不重要的是，live-manual使用SiSU来处理文本文件并生成多种格式的输出。建议查看SiSU的手册来熟悉它的标记，或者输入:

$ sisu --help markup

以下是一些可能有用的标记示例:

*{foo}* or !{foo}!

产生:foo或foo。用它来强调某些关键词。

/{foo}/

生产:foo。例如，使用它们作为Debian软件包的名称。

#{foo}#

生产:foo。例如，用于命令的名称。还要突出一些关键词或者路径之类的东西。

code{

  $ foo
  # bar

}code

产生:

$ foo
# bar

使用代码{ to open and }代码关闭标签。记住在每行代码的开头留一个空格是很重要的。

17.2 Guidelines for translators

本节讨论翻译实况手册内容时应考虑的一些一般事项。

作为一般建议，翻译人员应该阅读并理解适用于其特定语言的翻译规则。通常，翻译组和邮件列表提供有关如何生成符合Debian质量标准的翻译作品的信息。

Note: 译者还应阅读Contributing to this document. 特别是这一节Translation.

17.2.1 Translation hints

译者的作用是尽可能忠实地将原作者所写的单词、句子、段落和文本的意思翻译成目的语。

因此，他们应该避免添加个人评论或他们自己的额外信息。如果他们想为其他翻译相同文档的翻译人员添加注释，他们可以将其留在保留的空间中。也就是说，po文件中字符串的头文件前面有一个数字符号#。大多数图形翻译程序可以自动处理这些类型的注释。

然而，当且仅当使读者更清楚地理解一个难以理解的词或表达的意思时，在翻译文本的括号中包含一个词或表达是完全可以接受的。在括号内，译者应该用缩写“TN”或“译者注释”来表明这是他们的补充。

用英语写的文件大量使用了人称形式you。在其他一些没有这种特征的语言中，这可能会给人一种错误的印象，即原文是直接写给读者的，而实际上并不是这样。译者必须意识到这一事实，并尽可能准确地在自己的语言中反映出来。

前面解释的“假朋友”陷阱尤其适用于翻译。如果有疑问，仔细检查可疑假朋友的含义。

翻译人员最初使用pot文件，后来使用po文件，将在字符串中发现许多标记特性。他们可以翻译文本，只要它是可翻译的，但极其重要的是，他们使用与原始英文版本完全相同的标记。

尽管代码块通常是不可翻译的，但在翻译中包含它们是获得100%完整翻译的唯一方法。尽管一开始这意味着更多的工作，因为如果代码发生变化，可能需要翻译人员的干预，但从长远来看，这是在检查.po文件的完整性时识别已经翻译的内容和未翻译的内容的最佳方法。

翻译文本需要与原始文本具有完全相同的换行符。如果它们出现在原始文件中，请注意按“Enter”键或键入\n。例如，这些换行符经常出现在代码块中。

毫无疑问，这并不意味着翻译文本需要与英文版本具有相同的长度。这几乎是不可能的。

翻译人员不应该翻译:

- 版本的代码名(应该用小写字母写)

- 程序的名称

- 作为示例给出的命令

- 元数据(通常在冒号**:Metadata:**之间)

- 链接

- 路径