Documentation/Style guide

Overview
This page is a supplementary style guide for writing and editing technical documentation in MediaWiki and other technical spaces. It is intended to provide tips for writing clear, concise technical documentation in plain English, to highlight best practices and standards for a variety of technical documents used across projects, to share resources and knowledge about technical writing and editing in general.

"Good" technical documentation makes it easier for individuals to make technical contributions across Wikimedia projects. Whether you consider yourself a writer or not, your contributions are needed and appreciated.

For thorough coverage of general style and usage guidelines used across Wikimedia projects see the English Wikipedia's Manual of style.

English Wikipedia Manual of Style
The English Wikipedia Manual of Style is the definitive style manual for English language articles on Wikipedia. This is the primary page for the style guidelines: it covers certain topics (e.g. punctuation) in detail and summarizes the key points of others. The English Wikipedia Manual of Style represents an excellent reference for anyone writing or editing technical documentation in English across Wikimedia projects.

Additional guidelines for technical writing and editing
When many individuals, with varying levels of skills and experience, contribute to documentation it is important to follow clear standards and style guidelines for writing and editing. There are many style and usage rules for general writing -- far too many to remember -- and even more for technical writing. This page provides basic guidelines and tips to help get you started, as well as some specific information not covered in the Wikipedia Manual of Style.

Writing for technical audiences
Before you begin writing, it is important to think about the audience for your work. Who do you imagine will be reading this technical documentation? Where are they coming from? What level of familiarity do they have with the concepts you are presenting? What might they need to know in order to understand? Once you have an understanding of your audience, you will have a better sense of what you need to convey and how to to convey it.

Tips:


 * If you know your audience is highly technical and familiar with the processes you are describing, you do not need to explain basic concepts.
 * If you know your audience is learning or unfamiliar with the processes you are describing, include explanations of basic concepts and links to additional information.

Writing with a purpose
What purpose will your technical documentation serve? There are many reasons to write documentation. It is helpful to know why you are writing and what your goal is before you begin.

Is it to teach someone, like a newcomer, about a process or concept? Is it to show someone how to follow a process? Is it meant to provide background and context for a concept or process? Is it a reference intended to provide information?

Writing within a context
When deciding what to write and how to frame it for your reader, it can help to define a context or occasion for your writing. Your communication takes place in the context of a bigger situation. The context may be bounded by the era you are writing in, the type of technology available, your geographical location and culture, or the current culture and communication styles of the community you and your readers belong to. The occasion may be personal and arise from the situation that motivated you to create or improve a piece of documentation.

For example, if you are writing for technical documentation for Wikimedia projects, a context to consider is the culture that has been created by the individuals who volunteer, participate and interact across these projects. How could best position your writing within the context of this community and its culture to create the most meaningful and useful technical documentation?

Deciding on a document type
Once you have identified your main audience, purpose, and context of your documentation, you should put some thought into the type of document you will create.

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

For documentation written in English, Plain English  works best.

Tips:


 * Avoid ambiguity, jargon, and vague or unnecessarily complex wording.
 * Use words your audience will understand, and use just 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.

Voice and tone
What kind of voice and tone should technical documentation have?

Given the nature of a wiki -- a place where anyone can and should edit -- it can be difficult to institute and maintain a consistent voice or tone throughout all technical documentation.

Consider incorporating the following elements in your writing: Note: This is not meant to be an exhaustive list or a strict set of rules

Point of View

 * Use second person ("You" or assumed "You") when addressing your audience.
 * Avoid first person ("I"), unless you are writing a FAQ with questions asked from the first person perspective.
 * Most goal or process focused documentation should have an imperative mood.

Overview
All pages should include an overview 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) (Optional) Use case, case study, a practical understanding of the product, service or tool in action.

Table of contents

 * Each page should include a table of contents, so information can be accessed easily.

Titles and Headers

 * Use sentence case for headers.
 * Keep header fonts consistent throughout documentation.
 * Optional use of anchors to link sections or subsections in the same page.

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
 * Header
 * Content
 * Subhead if needed
 * Content

Basic text formatting guidelines
See the MediaWiki help page on formatting for basic guidance on how to format text in technical documentation.

Formatting code and other technical elements
Many situations call for text to be formatted to distinguish code and other technical elements from regular text.

General style guidelines

 * "Click Save or press enter", not "Hit Save or Enter".
 * We assume a basic level of familiarity with entering commands in a terminal. So write "Enter the following commands in a terminal window: " or "Enter  in a terminal" not verbiage like "open a UNIX shell and type the following commands and then press the Enter key."   If.

Markup

 * Don't overuse strong (bold) emphasis ; instead start with regular (italic) emphasis , or use a Caution, Note, or Warning template without any emphasis. In general,  pages have too many strong passages, so everything is yelling and nothing ends up important.
 * Use  or italic   for variables like message-key-name and sample names like My page title . Don't use punctuation such as , readers don't know the angle brackets are noise and will type them.
 * Use  for computer instructions, including wikitext markup.
 * Or use the  tag if it's more than a few words; you can use its  attribute to have syntax-colored code inline in a paragraph. See Extension:SyntaxHighlight for details.
 * Use manual for file paths such as LocalSettings.php by writing, which will output  (also the shorter, and equivalent version of.
 * Use  for actual text the user types into an input field or as a terminal command line.
 * Or use 
 * Within and  be sure to use   for variables and sample names so users know what to replace.
 * Sadly you can't use italic in the middle of a  source code block, so you have to fall back to YOURPASSWORD or The_page_title.

Useful templates
mediawiki.org pages are template-heavy, both to deliver consistency and to ease translation. Assume there's a template for whatever you're typing. When you create a new page, first view the source of a similar page to pick up e.g. the Extension infobox or MW file box.
 * ApiEx for api.php request URLs
 * Api help to transclude generated API documentation
 * caution, note, and warning boxes.
 * class doclink and file doclink to link to MediaWiki core's generated documentation]
 * git file to link to source code
 * for IRC link
 * Key press for, e.g. Ctrl+Shift+I
 * MW file for a box with info and links for a file in MediaWiki core
 * tracked for the related Phabricator task
 * RestOfVariableName for global variables

You use many of these with TNT or TNTN so they internationalize.

And of course interwiki links:
 * for tasks and project tags
 * for mailing lists
 * to English Wikipedia articles
 * for details about the WMF cluster.

Internationalization and localization
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.

Tips:
 * If a page has been translated, then click 'Edit source' to edit the entire page. The translation tag markers around section headings confuse section editing, and VisualEditor does not understand the, , and tags.
 * You can copy and paste existing idioms, but if in doubt leave out all translation machinery and just write English

Other technical documentation style guides
Below is a list of other technical documentation style guides:


 * Rackspace Style Guide
 * Gnome Documentation Style Guide
 * Google Developer Documentation Style Guide
 * Wordpress Documentation Style Guide
 * Atlassian Documentation Style Guide