作者：Kai Köhne，Mats Honkamaa
状态：草稿
类型：信息性文档
创建日期：2025-09-12
发布历史：https://lists.qt-project.org/pipermail/development/2025-September/046595.html
简介：本 QUIP 为 Qt 文档的写作风格制定了指导原则，重点关注语气、语法、语言运用和可读性。
清晰一致的写作对于 Qt 文档至关重要。本文档定义了写作风格标准，以确保 Qt 文档专业、易于访问且方便全球用户理解。
Qt 文档应：
确保内容正确。
确保内容清晰、简洁、明确。
以任务为导向，帮助用户高效地完成特定目标。
确保文档中术语的一致性。
确保文档易于非英语母语人士阅读，并充分考虑不同用户的认知、视觉和生理需求。
保持专业且平易近人的语气。
专注于用户需要了解的内容。
编写 Qt 文档时，请主要参考以下 QUIP（英语语言规范）。
如果此 QUIP 未涵盖特定问题，您可以参考《微软写作风格指南》，但并非必须遵循。
https://docs.microsoft.com/en-us/style-guide/
请始终使用美式英语拼写和术语，例如：
"color" 而非 "colour"。
"initialize" 而非 "initialise"。
"dialog" 而非 "dialogue"。
例外：当引用使用英式拼写的特定 API 名称时，请保留原始拼写。
尽可能使用主动语态：
使用："The function returns a pointer".
避免："A pointer is returned by the function".
尽可能使用现在时。
使用："This saves the file".
避免："This will save the file".
尽可能使用完整的句子，即使是项目符号列表也一样。
句子要简洁（尽量控制在 20 个单词以内）。
将最重要的信息放在最前面。
通常情况下，使用第二人称 you，就像在和读者对话一样。
避免使用第一人称 I、we，除非在教程和示例中。
指代 Qt 本身时，请使用 Qt 或 the framework 而不是 we。
选择简单明了的词语，而不是复杂的表达。
首次使用技术术语时，请给出定义。
除非为了精确表达，否则避免使用行话。
首次使用缩写时，请写出完整的缩写，并在括号中注明缩写（广泛认可的术语除外）。
请始终使用以下推荐术语：
使用 developer 而非 programmer 或 coder。
使用 user 指代终端用户（但请记住，大多数情况下使用第二人称）。
Select： 用于描述在用户界面中选择项目。这可以是按钮、复选框、列表中的值等等。
Clear： 用于描述从复选框中移除选中标记。
Go to： 用于描述打开菜单、跳转到选项卡或其他用户界面中的特定位置，或跳转到某个网站。
Enter： 用于描述在用户界面元素（例如文本框或组合框）中输入值。
Move, drag： 用于描述通过拖动、剪切粘贴或其他方法将任何内容从一个位置移动到另一个位置。请勿使用 drag and drop。
Press： 用于描述按下键盘按键或键盘快捷键。
Use： 当 select 可能造成混淆时使用。例如，"Use the arrow keys to navigate"。
Dialog - 而非 dialog box, pop-up, pop-up window。
Checkbox - 而非 check box。
Dropdown list 或 dropdown menu - 而非 dropdown 或 drop-down。
但是，尽量避免谈论用户界面元素。相反，要描述用户需要做什么。
有关完整的 Qt 特有术语和概念，请参阅 https://wiki.qt.io/Qt_Terms_and_Concepts
考虑用更具体的术语替换含义模糊的术语，例如：
不要使用 this，请明确指出您指的是什么。
不要使用 it，请重复名词或使用更清晰的指代。
不要使用 there are，请使用更直接的表达方式。
不要使用 enables，请使用 allows 或 lets you。
等宽字体格式： 用于文件名称、文件夹名称、文件扩展名、代码、命令行命令、变量名。
粗体格式：用于用户界面元素和键盘快捷键。
斜体格式：用于强调。
句子大小写 适用于大多数文本，包括：
常规句子和段落。
列表项。
表格单元格。
如果符合文档规范，标题（包括表格标题）可采用 标题大小写 格式。
一到九的数字用文字拼写。
十及以上的数字使用阿拉伯数字。
以下情况始终使用阿拉伯数字：
尺寸（5 像素）
版本号（Qt 6.0）
与代码相关的值
数量使用 more than 而不是 over。
可数项使用 fewer，不可数项使用 less。
提及版本时，请使用 later 和 earlier。例如："Qt 6.8 or later"。
对于无序项，请使用项目符号列表。
对于顺序项（例如分步指南）或优先级项（例如十大排行榜），请使用编号列表。
保持列表项结构平行。每个列表项应遵循相同的语法格式，例如，以动词开头。
如果任何一项是完整的句子，则以句号结尾。
列表开头应包含一个以冒号结尾的完整句子。
不要在列表项末尾使用分号、逗号或连词（例如 and 或 or）。
使用表格将更复杂的内容组织成两行或多行（加上一个标题行）两列或多列。
标题行文本应加粗。
表格单元格不要留空，请使用 N/A、Not applicable 或 None。
Note： 补充有用信息。
Warning： 防止出错的关键信息。
谨慎使用，以保持效果。
直接引用请使用 see。例如，“For more information, see www.qt.io”。
相关主题请在主题或页面末尾使用 see also。
避免在句子中使用不必要的链接，尤其是在任务主题和分步说明中。
避免使用 click here 或 this link。确保链接文本能够清晰地告诉用户链接指向哪里，尤其是外部链接。
为避免常见错误，请遵循以下规则：
请勿使用 please，除非客户被要求做一些不方便的事情，或者应用程序或网站本身造成了问题。
请勿使用 simply 或 just（暗示任务微不足道）。
请勿使用 obviously 或 clearly（假设读者具备相关知识）。
请勿混用或使用多个比喻。
请勿使用感叹号（祝贺信息除外）。
请勿使用拉丁语缩写（例如，请使用 for example 而不是 e.g.）。
提交文档前：
检查（美式英语）拼写和语法。
确保术语使用一致。
确保以主动语态为主。
确认当前行为描述使用现在时。
检查代词指代是否清晰。
检查列表和表格格式是否正确。
确保语气专业且平易近人。
检查文本格式是否正确。例如，文件名、代码、UI 控件等。
图片应包含描述性替代文本。
链接应包含描述性文本。
一致的写作风格能够提升Qt文档的质量和易用性。
这些指南确保所有Qt文档都保持专业、
清晰且易于理解的标准，从而服务于我们的全球用户群体。