帮助文档/格式指南
概述
本格式指南为在MediaWiki和其他技术空间中编写技术文档提供指导。 本文提供了一些提示，可帮助您以通俗易懂的语言编写清晰、简洁的技术文档。本文还链接到有关技术写作和平常编辑的其他资源。
好的技术文档使人们更容易为维基媒体项目做出贡献。 在编写文档时遵循明确的标准和格式指南非常重要，尤其是当贡献者和读者具有不同的技能和经验水平时。 无论您是否认为自己是一名编者，您的贡献都是被需要和赞赏的！
英文维基百科格式手册
英文维基百科的格式手册详细介绍了通用写作主题（如标点符号），并总结了其他格式指南的要点。 对于跨维基媒体项目用英语编写技术文档的人来说，它可能是一个有用的参考，特别是当本地wiki没有更具体的指导方针时。
本页提供了基本指南和提示，可帮助您开始编写技术文档。它包括一些特定于技术文档的信息，这些信息未在维基百科格式手册中涵盖。
用户体验设计
如需用户体验设计（UX design）、UX 写作及相关建议，请参阅 Codex 中的《维基媒体 Codex 风格指南》。 UX 写作专注于界面（UI）中出现的文字，使交互更清晰、更易理解。 例如，与其显示技术性错误提示 “Authentication failed (error code 503)”，有效的 UX 写作会改为 “无法登录，请检查密码后重试”。
关于用户体验（UX）写作及相关建议，请参阅《维基媒体 Codex 风格指南》。
受众和内容
为技术读者编写
在开始写作之前，请考虑您作品的受众：
- 谁将阅读此技术文档？
- 他们来自哪里？
- 他们对您介绍的概念有多熟悉？
- 他们可能需要知道些什么才能理解？
一旦您了解了您的受众，您就会更好地了解您需要传达什么。
- 如果您知道您的受众是技术性很强并且熟悉您所描述的内容，那么您不需要解释一些基本概念。
- 如果您知道你的受众是学习中或不熟悉您所描述的内容，那么需要增加说明基本概念和其他信息的链接。
有目的地编写
您的技术文档将用于什么目的？编写文档的原因有很多。 在开始之前了解您为什么写作以及您的目标是什么是有帮助的。
- 是教某人（比如新人）关于一个流程或概念的知识吗？
- 是为了向某人展示如何遵循流程吗？
- 它是否旨在为概念或流程提供背景和说明？
- 它是旨在提供信息的参考资料吗？
编写一个背景
在决定写什么以及如何为读者构建它时，定义写作的背景或场合会有所帮助。 您的交流发生在更大的背景下。 背景可能会受到您写作的时代、可用技术类型、您的地理位置和文化或读者当前文化和交流方式的限制。 这个情况可能是个人的，源于促使您创建或改进文档的情况。
例如，如果您正在为维基媒体项目编写技术文档，请考虑参与这些项目的个人所创造的文化。 您如何在这个社区及其文化的背景下最好地定位您的作品，以创建最有意义和有用的技术文档？
用户测试和反馈
创建技术文档，将想法和概念传达给真实的用户受众。 自然，这些读者应该在文档的编写和修正中发挥关键作用。 考虑收集有关用户体验信息的方法。 请花一些时间回答以下问题：
- 您的文档是否包含反馈机制？
- 您能否及时与读者进行对话以做出改进？
- 您能否使用Stack Overflow等论坛或邮件列表来检查您的文档是否回答了人们对您的特定主题的最常见问题？
准确度和一致性
准确和一致使得跨MediaWiki/维基媒体项目访问、阅读和创建技术文档变得更加容易。 技术文档是为广大读者编写的，并由各种贡献者编辑。
语音、语气、语法用法、样式和格式在技术文档和类似内容集合中应保持一致。 这有助于读者了解如何导航信息，并使贡献者更容易了解如何编辑和添加新信息。
选定一种文档类型
首先确定主要受众、目的和背景，然后决定将创建哪种类型的文档。
| 受众示例 | 目的[1] | 可选的文档类型 | 示例 |
|---|---|---|---|
| 想要了解如何成为 Toolforge 用户的新手 | 学习 | 教程、常见问题与解答、入门指南 | 云 VPS 和 Toolforge 的常见问题与解答 |
| 正在处理一个已知问题的有经验的技术贡献者 | 达成目标 | 流程说明、“如何实现 xxx”指南 | 我的第一个 Flask OAuth 工具 |
| 想要了解 ORES 的历史及其演变的人 | 了解 | 解释性文章、博客文章、“概述” | 人工智能服务 “ORES” 为维基百科编辑者提供“火眼金睛”，以识别不良编辑 |
| 想要了解 SSH 密钥定义的人 | 查看说明 | 参考指南、术语表 | 术语表 |
多语言
本节简要提到了一些值得在其他地方更详细探索的话题。 始终将用词表达与维基词典上的内容进行核对： 维基词典的词条涵盖数百种语言，明确说明了单词的语法和词汇特征及其词形变化，提供详细的语境标签（包括行话、英式英语与美式英语等），并展示这些词在数百种其他语言中的可译性。
简明英语
请注意：访问这些页面的许多用户的母语并非英语。
对于用英语撰写的文档，简明英语（也称 plain language）效果最佳。 清晰的写作最容易被不同背景的读者理解，同时也最便于翻译。 在 Meta-Wiki 的 Tech News 写作指南中，有一些很好的工具可以帮助检查你的写作。
- 避免模糊表达、行话以及含糊或复杂的措辞。
- 使用读者能够理解的词汇，并确保有足够的文字传达信息。
- 对于可能不为新手所熟悉的术语，请进行定义说明。
- 保持段落和句子简短、精炼。
- 自行决定是否使用缩写形式，但要保持一致性。
语气和语调
MediaWiki 是一个人人都可以编辑的平台。 因此，在文档中保持一致的语气语调可能会有困难。
在实际写作中请考虑使用以下元素：
| 语气语调 | 这意味着什么？ | 反面示例（避免这么写） | 正面示例（建议这么写） |
|---|---|---|---|
| 友善的 | 技术文档不意味着必须充满学术化或枯燥的语气。 像他们亲自在场一样，向你的听众写作。 | 在开始之前，用户必须创建一个账户。 | 创建账号以开始。 |
| 专业的 | 技术文档应该是友善的，但同时需要保持专业性。 使用 Inclusive language。 | 不要进行大量修改。 | 尽量只做最小范围的修改。 |
| 积极的 | 避免使用否定句式。应以正面表述说明应做的事项。 复杂的否定句更难让人理解！ | 如果你不 “XYZ”，“N” 就不会发生。 | 为了达成 “N”，请 “XYZ”。 |
| 主动语态 | 尽量使用主动语态，但在需要委婉表达时可使用被动语态。 | 此扩展必须被注册。 | 应该注册此扩展。 |
| 无性别的 | 使用中性语言 假设您的听众包括所有性别认同的人。 | 当他点击“保存” | 当用户点击“保存” |
| 包容的 | 避免使用可能无意强化不当刻板印象的常用词汇或短语，可选用替代表达。 | 这个界面太神经了。（可能冒犯到精神疾病患者） | 这个界面有待改进。 |
| 避免造成挫败感 | 避免使用 “easy”（容易）和 “simple”（简单）等词，因为这些词可能让技术水平较低的用户感到挫败。 | 只需创建一个用户帐户。 | 创建一个用户帐户。 |
| 避免口语化 | 使用日常口语、俚语、笑话、双关语或特定表达，可能会让非英语母语用户或来自其他地区的人感到困惑。 | Creating a user account is a piece of cake（“小菜一碟”）. | Creating a user account requires two steps（需要两个步骤）. |
视角/人称
- Use second person ("You" or assumed "You") when addressing your audience.
- Avoid first person ("I" or "we"), unless you are writing a FAQ with questions asked from the first person perspective.
- Use an imperative mood for most documentation focused on goals or process.
Dates
- Always use the full, four-digit year.
- Use absolute dates ("in May 2037") instead of relative dates ("next year in May").
- Avoid adding dates that will require regular manual updates. Example: Write
{{#time: Y }}instead of 2026 when referring to the current year, no matter what year it is currently.
Structuring pages
Overview
All pages should include an overview section (also called the Lead section) that explains:
- Purpose of the page
- Audience of the page
- Prerequisites the reader will need to know before proceeding (Ex. a working knowledge of Python)
- Software or tools the reader will need to complete the processes or tasks outlined on the page (Ex. Java installed)
- Use case, case study, a practical understanding of the product, service or tool in action. (optional)
Table of contents
- Each page should include a table of contents, so information can be accessed easily.
Titles and headings
- Use sentence case for headings.
- Keep heading fonts consistent throughout documentation.
- Optional use of anchors to link sections or subsections in the same page.
- Add a blank line after section headings. This impacts how the content is packaged for translation.
- Do not put a heading before your overview or lead section.
- Do not put links inside section headings: it impacts mobile usability.
Information flow
Technical documentation pages should follow a consistent pattern across content collections.
An ideal pattern for each page might be:
- Page title
- Introduction/Overview
- Heading
- Content
- Subheading if needed
- Content
- Subheading if needed
- Content
Formatting text
Formatting code examples and other technical elements
Formatting distinguishes code and other technical elements from regular text.
| Purpose | Wiki-Markup | Result | Situation |
|---|---|---|---|
| Plain code | <code>code</code>
|
Plain code
|
Use for short strings of code, including wikitext markup.
Within |
| Syntax highlight |
<syntaxhighlight lang="css">
.citation {
margin: 0;
}
</syntaxhighlight>
Text before |
.citation {
margin: 0;
}
Text before |
Use the <syntaxhighlight lang="...">...</syntaxhighlight> tag to document a few lines of code, and preserve whitespace and linebreaks. The inline attribute allows using it within an existing paragraph.
Note you cannot use italic in the middle of a 有关更多详细信息，请参见Extension:SyntaxHighlight（语法高亮）。 |
| Code sample of non-wikitext using {{Codesample}} window | {{Codesample
| lang = yaml
| name = Example.yaml
| scheme = light
| line
| code =
}}
{{Codesample
| lang = js
| name = Example.js
| code =
}}
{{Codesample
| scheme = light <!--scheme = dark also possible-->
| lang = shell-session
| code =
}}
|
Example.yaml # {{Codesample}} example
version: v1
Example.js function Model() {
/** Example */
}
$ echo "hello world!"
$ echo "hello world!"
|
Stylised code sample in window with file name tab.
If only the header is needed and you're using syntaxhighlight, then place {{Codesample-header}} before |
| Preformatted | <pre>preformatted text
|
preformatted text
with indent
|
Same as above (preserve whitespace and linebreaks), but without coloring. |
| Keyboard input | <kbd>keyboard 123</kbd> (vs keyboard 123)
|
keyboard 123 (vs keyboard 123) | Use <kbd>...</kbd> for actual keyboard input - the text a user types into an input field or at a terminal command line. It displays in plain monospace.
|
| Variables | <var>variable</var>
''italics''
|
variable
italics |
Use italics for variables like message-key-name and sample names like My page title.
Do not use punctuation such as <YOURPASSWORD>, because readers don't know the angle brackets are noise and will type them. |
| Bold | '''bold'''
|
bold | Generally only used for the first instance of the page-title, and for rare emphasis of keywords to enable easier skimming of lists or paragraphs. |
| Quotations | "quotation marks"
Text before
Text after |
"quotation marks"
Text beforeText after |
Use quotation marks for brief pieces of content quoted from other sources.
Use blockquote for longer pieces of content. |
| Abbreviations | JavaScript (JS)
|
JavaScript (JS)
JS |
You should define abbreviations the first time they are used. Use either plain text and parentheses, or the HTML abbr tag. |
| Keypress | {{Key press}}
|
Ctrl+⇧ Shift+I | 显示特定的键盘按下或组合。 可视化编辑器/主题/键盘快捷键有大量示例。
Note: This template might not exist on other wikis. |
| Button | {{Button}}
|
显示预览 | Showing UI buttons that need to be clicked on.
Note: This template might not exist on other wikis. |
Links
| Type | Purpose | How to implement | Example |
|---|---|---|---|
| Local | Link to other MediaWiki pages |
|
MediaWiki |
| Translated Target | Link to other translated MediaWiki pages | [[Special:MyLanguage/Foo|Foo]]
|
How to contribute |
| Interwiki | Link to page belonging to a different Wikimedia project |
|
Documentation page on Wikipedia |
| External | Link to external pages | [https://www.example.org Example.org]
|
Example |
Templates
Templates are often used on MediaWiki.org pages. Templates can help to maintain consistency and can make it easier to translate information.
Below are some common templates.
Templates for page formatting
- {{Caution}}, {{Fixtext}}, {{Note}}, {{Tip}}, {{Todo}}, {{警告/核心}} – for styles of inline highlight boxes
- {{Fixme}}, {{Historical}}, {{Notice}}, {{已过时}}, {{Update/zh}} – for page/section message boxes
- {{Main}}, {{参见}} – for page/section hatnotes (a short note placed at the top of an article)
Templates for MediaWiki core and Git source
- {{Class doclink}}, {{File doclink}}, {{Js doclink}} – to link to MediaWiki core's generated documentation
- {{MW file/zh}} – for a box with info and links for a file in MediaWiki core
- {{Git file}} – to link to source code
Templates for Phabricator
- {{Ptag}} – for the top-right-of-page Phabricator project tag
- {{Tracked}} – for the related Phabricator task
Other useful templates
- {{irc|wikimedia-tech}} – for IRC link
- {{Key press}} – for, e.g. Ctrl+⇧ Shift+I, and {{Button}} for, e.g. 显示预览
- {{ApiEx}} – for api.php request URLs
- {{Api帮助}} – to transclude generated API documentation
- {{Wg}} – for global variables
- {{Tag}} – for a quick way to mention an XML-style tag in a preformatted way
Mobile devices
General recommendations for mobile-friendly wiki pages are already available on 維基媒體維基上對移動版條目友善的建議 and 移动版入口/移动主页格式. This section provides tips useful in the context of documentation, developed as part of T383117.
- Test your documentation on a mobile device. You can also do this in your desktop browser by using the Responsive Design Mode in Firefox and Safari, or the Device Toolbar in Chrome. Be prepared to make changes to the page if you notice any problems. The most common issues are: unnecessary margins or indentation, incorrect text wrapping, and block elements not fitting in their containers.
- Pages that only include headings, regular paragraphs, and lists are almost certain to render correctly on mobile devices. Such pages shouldn't require any custom styling but are still worth testing.
- When designing a page element or template from scratch using HTML and CSS:
- Use Extension:TemplateStyles（模板样式） to access CSS features that you can't add directly to the style property of an HTML tag.
- Be prepared to write separate CSS rules for desktop and mobile (example).
- Use CSS features such as media queries, flexbox, and grid layout to ensure your custom element looks good on all types of devices.
- Use tables only to present data. Don't use tables to design content layouts or menus.
- If you are including a code snippet on the page, make sure it's legible on narrow screens. Some code snippets look OK with text wrapping, but some don't. In the latter case, set the style to
overflow-x: auto; white-space: pre;to preserve code layout.
Translations
All pages on mediawiki.org are candidates for translation into multiple languages. MediaWiki.org is a multilingual wiki, it uses the Translate extension to present alternative translations and manage the translation of pages.
- If a page has been translated, then click
编辑源代码to edit the entire page.
<languages>, <translate>, <tvar>
- Do not copy and paste existing markup.
See also
- Some other technical documentation style guides:
- Wikiversity:Technical writing
- Other language related resources: