Community Tech/Documentation

The Community Tech Documentation Initiative is an attempt to document a set of practices that our team undertakes with regard to writing user and sysadmin documentation for our projects.

We work on many different codebases and software components across the Wikimedia universe, and with them come various different ways of maintaining documentation (including, for some, no established way at all!). This documentation initiative is about making sure we all know what goes where, how it should be written, and what tools should be used.

We want our projects to be well-documented not only because it'll help people learn how to use them and give us somewhere to link to when people ask about them, but also because Community Tech generally moves on from projects once we're done and it's good for future teams to be able to pick up where we leave off.

In writing documentation we aim to:

• ensure that documentation gets written for end users and sysadmins;
• keep the documentation up to date as we change the software;
• make the documentation localizable (although, this applies somewhat less to sysadmin docs)

Note that we don't really cover developer documentation in this initiative, because that is a topic that's well covered and generally already happens in-code. There are some exceptions to this, such as MediaWiki core's docs/ directory (which is being phased out^{[citation needed]}), but generally Community Tech projects assume that a new developer will be able to clone a repository and get it up and running by reading the README.md, CONTRIBUTING.md, CHANGES.md, and other included files. More work does need to be done with publishing our developer docs to doc.wikimedia.org. This also includes API and CLI documentation, which should both be generated from in-code comments (although this is not yet always done).

To that end, the audiences that we do write for are end-users (with possibly little technical knowledge, or even Wikimedia knowledge), and system administrators (who need to install, upgrade, and maintain our software but who we don't assume know anything about its internals).

The components that we work on are MediaWiki core, extensions, and Toolforge tools. Occasionally there have been other places for deployment, such as a browser extension, but that has been rare.

Docs-as-code

The 'docs-as-code' approach (or 'docs-in-code') is a popular system of documentation (outside Wikimedia). It involves storing documentation text files (usually Markdown) within the same repository as the main software code, and keeping this documentation up to date as the code changes. These files are then compiled to HTML and make available on the web.

The primary advantages of this approach are that the documentation only ever needs to address the current state of the code (i.e. doesn't always have to call out differences of behaviour between versions), and continuous-integration processes can be put in place to help ensure that every code change is either accompanied by a documentation change or a declaration that no such change is required. Version- and language-switching UI elements are usually available on every page of the documentation.

Common tools for docs-in-code are Sphinx and MkDocs. The former is the basis for the popular Read the Docs website, and the latter is used for the new Wikimedia Developer Portal. Whatever we use is mostly likely going to comprise Markdown files in a docs/ directory (with optional Yaml frontmatter in the files).

The primary problems with docs-in-code for Wikimedia software are that it can't be searched along with all other documentation, and that it can't be localized with our existing tools (TranslateWiki or on-wiki with the Translate extension).

Documentation-driven development

Documentation-driven development is a methodology of in which the documentation is written first, before any code. It can help focus the development to be undertaken from the point of view of the user, and so can highlight issues earlier than otherwise might be the case. Draft documentation can be shown to the users and their feedback given in a much shorter time.

DDD involves writing about a new feature or other software change as though it already exists, explaining it to the user. It is also related to similar documentation-first ideas, such as GitLab's Handbook-first approach which can help with keeping documentation out of chat channels and in places where it's more likely to be of use.

With the right tools, drafting the documentation need not be the responsibility of the engineers who will be working on the code.

What are different types of documentation that we want to cover?

Every component has end-user documentation on mediawiki.org (in the Help namespace). Developer documentation is within the code repositories, and on pages on mediawiki.org. Sysadmin documentation pages live on Wikitech. (Project updates and discussion happen on Meta, but all non-temporal documentation would be on the other wikis).

How do we track if documentation to sufficiently added?

Only one of the three required documentation types added i.e. only end-user docs.

Two of the three required documentation types added i.e. end-user docs and developer docs.

All required documentation types added which means: sysadmin docs, end-user docs and developer docs.

Locations of docs

Type ↓      Audience →	User	Admin
MediaWiki core	mediawiki.org Help namespace	mediawiki.org Manual namespace
MediaWiki extensions	mediawiki.org Help:Extension namespace prefix	mediawiki.org Extension namespace
Tools	t.b.d.	Wikitech wiki

Proposal: a documentation library for tools

A simple Toolforge tool that will download the docs/ directories from our tools' repositories and compile them to small static HTML websites, similarly to how Read the Docs works. It will:

• Provide an overview of all tools. This will also use the user_docs_url data from Toolhub, for tools that host their user documentation elsewhere.
• Not require any particular registration or configuration of tools in order to have them included (it can check Toolhub, and be opinionated about what structure etc. it accepts).
• Provide search across all tools, and also within each tool's documentation.
• Allow for translations of pages, with the translations being committed back to the original repository (maybe only if its on GitLab?).
• Make it easy to set up a new tool's documentation directory, e.g. via a one-click merge-request creation.

More details of the tool will be added to its own documentation, as a demonstration of the DDD process!