Documentation/Technical style guides and templates

This page contains resources to help you create and improve technical documentation for Wikimedia projects.

Style guides

Style and grammar

• Wikipedia manual of style - This is the primary style guide for Wikimedia projects. You should use this as a reference for any general writing you are doing.
• MediaWiki technical documentation style guide - This resource is a secondary style guide meant specifically for technical documentation on Wikimedia projects. You should use this to help guide the style and formatting of technical aspects of projects.
• Inclusive language guide - We want to encourage a culture of inclusivity, and part of doing that is making sure we use appropriate language where we can. This guide provides information about using inclusive language in your technical documentation.

Specific types of technical documentation

This section is for resources for technical writers working on specific kinds of documentation.

API documentation

• https://developers.google.com/style/api-reference-comments
• Documenting APIs - a resource for individuals who want to learn how to document APIs.
• The ten essentials for good API documentation

PAWS/Jupyter notebooks

• PAWS examples and recipes - This page contains a number of example PAWS notebooks that can give you some ideas about how to format your own.

Runbooks

• Cloud VPS Runbooks - This page provides some good general tips about how to create runbooks.

Templates and formatting

This section provides resources about templates for transcluding and formatting doc content on wikis. For documentation templates and outlines, see Documentation/Toolkit.

• Text formatting templates - A list of useful templates for tech docs on mediawiki.org, with examples of how they appear and how to use them.
  • Some additional MediaWiki template examples are at Documentation/Style guide#Templates.
• Wikitech documentation templates - A list of useful templates for tech docs on Wikitech, with examples of how they appear and how to use them.
• MediaWiki templates - Overview of Mediawiki templates and how to use them to transclude(embed) content across a number of pages.
• Collapsible page elements examples - A demo page showing all the ways you can make page elements expand and collapse, which can be useful for avoiding information overload through progressive disclosure.

Translation

Best practices or writing simple technical English for translation:

• Plain English - This page has information on using simple English.
• Simplified Technical English - This page contains information about and some guidelines for writing in Simplified Technical English.

Working with translated wiki pages involves navigating translation markup. For more info, see Documentation/Style guide#Translations and Help:Extension:Translate/Page translation example#Step 4: Making changes.

Spelling, grammar and writing aids

Many writers benefit from running spelling and grammar checks on their work. Not only can these check for issues with your document, but they can also help you become a better writer by identifying your more common errors.

• https://www.expresso-app.org/
• https://www.languagetool.org/
• https://editsaurus.tylerwalters.com/

Learn about technical writing

• Google's technical writing courses
• Write the docs - Beginner's guide to docs
• https://thegooddocsproject.dev/
• Presentations about technical writing from Wikimedians
  • Technical Documentation 101
  • Technical Writing Best Practices
  • Building User-Friendly Guides for Wikimedia Tools
  • Plant trees: Writing documentation as a community