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.

Clarity and consistency
Your goal is to make accessing, reading, and creating technical documentation for Wikimedia easier and more intuitive by promoting clarity and consistency throughout. Technical documentation is written for a wide audience and edited by a variety of contributors.

Voice, tone, grammar usage, style, and format should be consistent across technical documentation and similar content collections. This helps readers learn how to navigate information and makes it easier for contributors to understand how to edit and add new information.

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.
 * Use contractions or don't. Just be consistent.

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 thorough guidance on formatting text.

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

Tips

 * Log in vs Login: Log in can be used when you are directing a user to enter credentials into a UI. Login is a name for the username and password or the UI (aka Login box).

Hooks and events
As says, a hook is the "clump of code and data that should be run when an event happens" in the client(s) of an event such as.


 * Use manual for file paths such as LocalSettings.php by writing, which will output  (also the shorter, and equivalent version of

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