技术文档/格式指南

概述

本格式指南为在MediaWiki和其他技术空间中编写技术文档提供指导。 本文提供了一些提示，可帮助您以通俗易懂的语言编写清晰、简洁的技术文档。本文还链接到有关技术写作和平常编辑的其他资源。

好的技术文档使人们更容易为维基媒体项目做出贡献。 在编写文档时遵循明确的标准和格式指南非常重要，尤其是当贡献者和读者具有不同的技能和经验水平时。 无论您是否认为自己是一名编者，您的贡献都是被需要和赞赏的！

英文维基百科格式手册

英文维基百科的格式手册详细介绍了通用写作主题（如标点符号），并总结了其他格式指南的要点。 对于跨维基媒体项目用英语编写技术文档的人来说，它可能是一个有用的参考，特别是当本地wiki没有更具体的指导方针时。

本页提供了基本指南和提示，可帮助您开始编写技术文档。它包括一些特定于技术文档的信息，这些信息未在维基百科格式手册中涵盖。

受众和内容

为技术读者编写

在开始写作之前，请考虑您作品的受众：

• 谁将阅读此技术文档？
• 他们来自哪里？
• 他们对您介绍的概念有多熟悉？
• 他们可能需要知道些什么才能理解？

一旦您了解了您的受众，您就会更好地了解您需要传达什么。

• 如果您知道您的受众是技术性很强并且熟悉您所描述的内容，那么您不需要解释一些基本概念。
• 如果您知道你的受众是学习中或不熟悉您所描述的内容，那么需要增加说明基本概念和其他信息的链接。

有目的地编写

您的技术文档将用于什么目的？编写文档的原因有很多。 在开始之前了解您为什么写作以及您的目标是什么是有帮助的。

• 是教某人（比如新人）关于一个流程或概念的知识吗？
• 是为了向某人展示如何遵循流程吗？
• 它是否旨在为概念或流程提供背景和说明？
• 它是旨在提供信息的参考资料吗？

编写一个背景

在决定写什么以及如何为读者构建它时，定义写作的背景或场合会有所帮助。 您的交流发生在更大的背景下。 背景可能会受到您写作的时代、可用技术类型、您的地理位置和文化或读者当前文化和交流方式的限制。 这个情况可能是个人的，源于促使您创建或改进文档的情况。

例如，如果您正在为维基媒体项目编写技术文档，请考虑参与这些项目的个人所创造的文化。 您如何在这个社区及其文化的背景下最好地定位您的作品，以创建最有意义和有用的技术文档？

用户测试和反馈

创建技术文档，将想法和概念传达给真实的用户受众。 自然，这些读者应该在文档的编写和修正中发挥关键作用。 考虑收集有关用户体验信息的方法。 请花一些时间回答以下问题：

• 您的文档是否包含反馈机制？
• 您能否及时与读者进行对话以做出改进？
• 您能否使用Stack Overflow等论坛或邮件列表来检查您的文档是否回答了人们对您的特定主题的最常见问题？

准确度和一致性

准确和一致使得跨MediaWiki/维基媒体项目访问、阅读和创建技术文档变得更加容易。 技术文档是为广大读者编写的，并由各种贡献者编辑。

语音、语气、语法用法、样式和格式在技术文档和类似内容集合中应保持一致。 这有助于读者了解如何导航信息，并使贡献者更容易了解如何编辑和添加新信息。

Deciding on a document type

参见：​Documentation/Technical documentation templates and suggestions

Identify your main audience, purpose, and context first to decide on the type of document you will create.

Example Audience	Purpose	Potential Document Types	Example
Newcomer interested in learning how to become a Toolforge user	To learn	Tutorial, FAQ, Getting Started guide	Cloud VPS and Toolforge FAQ
Experienced technical contributor trying to work through a known problem	To achieve a goal	Walk-through, How-To guide	My First Flask OAuth Tool
Individual trying to understand the history of ORES and how it evolved	To understand	Explanatory article, blog post, "overview"	Artificial intelligence service “ORES” gives Wikipedians X-ray specs to see through bad edits
A person looking for a definition of SSH keys	To inform	Reference guide, glossary	Glossary

Language

参见：​The "Writing clearly" article on Wikiversity

This section briefly mentions some topics worth exploring elsewhere in more detail. Always check your words and expressions against these criteria on Wiktionary: Wiktionary entries cover hundreds of languages, explicitly state the grammatical and lexical features of words and their declensions, provide detailed context labels (including about jargon, UK vs. USA English) and expose how translatable terms are in hundreds of other languages.

Plain English

Please remember: many visitors to these pages are not native English speakers.

For documentation written in English, Plain English (also called plain language) works best. Clear writing is the most understandable by diverse audiences, and is also easiest to translate. There are a number of good tools for checking your writing, at Tech News' Writing Guidelines on Meta-Wiki.

• Avoid ambiguity, jargon, and vague or complex wording.
• Use words your audience will understand, and enough words to convey your message.
• Define terms that may not be obvious to individuals who are new to the subject matter you are writing about.
• Keep paragraphs and sentences short and concise.
• Use contractions or don't. Be consistent.

Voice and tone

MediaWiki is a place where anyone can edit. Thus, it can be difficult to maintain a consistent voice and tone in the documentation.

Consider using these elements in your writing:

Voice and tone	What this means	Instead of this	Try This
Friendly	Technical documentation does not need to sound academic or dry. Write to your audience as if they are there in person.	Before beginning, the user must create an account.	Start by creating an account.
Professional	Technical documentation can be friendly, but should remain professional. Use Inclusive language .	Don't make a bazillion changes.	Try to make minimum changes.
Positive	Avoid using negative sentence constructions. Explain things in terms of what to do. It is harder to mentally parse a complex negative sentence!	N won't happen, if you don't XYZ.	To make N happen, do XYZ.
Active	Try to use active voice, except when diplomacy calls for passive voice.	The extension must be registered.	You must register the extension.
Non-gendered	Adopt gender-inclusive language. Assume your audience comprises all gender identities.	When he clicks Save	When the user clicks Save
Inclusive	Use alternatives to common words or phrases that may unintentionally reinforce inappropriate stereotypes.	This UI is crazy.	This UI could be improved.
Free of frustration	Avoid terms like "easy" and "simple" which can be frustrating for less tech-savvy users.	Simply create a user account.	Create a user account.
Free of colloquialisms	It can be confusing to use colloquialisms, jokes, puns, or turns of phrase that non-native English speakers or individuals from other regions might not easily understand.	Creating a user account is a piece of cake.	Creating a user account requires two steps.

This is not meant to be an exhaustive list or a strict set of rules.

Point of view

The following guidance overrides the general Wikipedia style guidelines for pronouns, but only for technical documentation.

• 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 2024 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:

1. Purpose of the page
2. Audience of the page
3. Prerequisites the reader will need to know before proceeding (Ex. a working knowledge of Python)
4. Software or tools the reader will need to complete the processes or tasks outlined on the page (Ex. Java installed)
5. 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.

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

Formatting text

主页面： Help:Formatting

Formatting code examples and other technical elements

Formatting distinguishes code and other technical elements from regular text.

Purpose	Wiki-Markup	Result	Situation
Code	‎<code>code‎</code>	code	Use for short strings of code, including wikitext markup. Within ‎<code>...‎</code>, use ''italics'' to indicate variables and sample names so users know what to replace.
Syntax highlight	<syntaxhighlight lang="css"> .citation { margin: 0; } </syntaxhighlight> Text before <syntaxhighlight lang="css" inline>.foo {margin: 0;}</syntaxhighlight> text after.	.citation { margin: 0; } Text before .foo {margin: 0;} text after.	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 <syntaxhighlight lang="foo">...</syntaxhighlight> block, so you have to fall back to YOURPASSWORD or The_page_title to indicate variables. 有关更多详细信息，请参见Extension:SyntaxHighlight 。
Preformatted	‎<pre>preformatted text       with indent‎</pre>	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. Sometimes bold is overused for emphasis. You may consider using a template instead, e.g. {{Caution }}, {{Note }}, or {{警告/核心 }}.
Quotations	"quotation marks" Text before ‎<blockquote>blockquote‎</blockquote> Text after	"quotation marks" Text before blockquote Text after	Use quotation marks for brief pieces of content quoted from other sources. Use blockquote for longer pieces of content.
Abbreviations	JavaScript (JS) <abbr title="JavaScript">JS</abbr>	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

主页面： Help:Links

Type	Purpose	How to implement	Example
Local	Link to other MediaWiki pages	[[Foo]] [[Foo|Bar]]	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	[[phab:T2001]] for tasks and project tags [[mail:wikitech-l]] for mailing lists [[w:en:foobar]] to English Wikipedia articles [[wikitech:foobar]] for details about the WMF cluster [[gerrit:604435]] for change requests in Gerrit	Documentation page on Wikipedia
External	Link to external pages	[https://www.example.org Example.org]	Example

Templates

参见：​Documentation/Style guide/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 }}, {{已过时 }}, {{更新 }} - 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

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 'Edit source' to edit the entire page.

Wrongly placed translation tag markers around section headings can confuse section editing, and as of July 2015 VisualEditor does not understand the following tags: ‎<languages>, ‎<translate>, ‎<tvar>

• Do not copy and paste existing markup.

If in doubt, focus on writing a good text and let someone else handle the Translate markup.

See also

• Some other technical documentation style guides:
  • Google Developer Documentation Style Guide
  • MDN Web Docs Writing Style Guide
• Wikiversity:Technical writing
• Other language related resources:
  • Inclusive language
  • word-list
  • Naming things

Footnotes