User:Zakgreant/MediaWiki Technical Documentation Plan

This document is a draft.

As such, it may be varying degrees of ugly, incomplete, incoherent or otherwise broken. Please review and comment.

If you wish to discuss, please catch me on IRC (zakg on irc://freenode#mediawiki) or via email zak+mediawiki@fooassociates.com

DRAFT // Last Updated: 2020-04-06

MediaWiki Technical Documentation Plan

This is a plan to improve MediaWiki’s developer documentation by making small, incremental improvements to the existing documentation process and infrastructure.

The recommendations in this plan are supported by:

• background information to help readers understand the current state of MediaWiki’s developer documentation. This information helps give perspective on the proposed changes.
• profiles of the groups who care about MediaWiki’s developer documentation. The needs of these groups shaped the goals and recommendations in this plan.
• lists of principles (such as “Keep It Simple”) and goals (such as “Easy-to-read”) used to guide the recommendations made in this plan.
• detailed information on the proposed changes to the existing documentation process.
• various supporting materials, including suggestions for writing style, recommendations around wiki structure and an overview of risks to be managed.

Your Role

If you are reading this plan, you likely care about and have experience with the MediaWiki developer documentation and the MediaWiki community.

As you read, please take a moment to add your questions and comments to the discussion page or add to the plan itself.

Technical Documentation Process Summary

Abstractly, the technical documentation process in this plan is designed to:

• Make it easy
• for any reader of the developer documentation
• to improve the documentation
• in small and simple steps
• that can be done independently of each other (when needed).

Background information and Plan framework

State of MediaWiki’s Developer Documentation

MediaWiki’s developer documentation is a large and useful body of work that consists of three primary resources, and various secondary and supporting resources. The three primary resources are:

• a Technical Manual on mediawiki.org, that focuses on how-to documentation and reference materials. As a whole, the technical manual varies greatly in accuracy, completeness, content, page structure, translation status, tone and quality. The structure of the documentation as a whole is also quite variable – categories are used haphazardly, pages are orphaned, and there are stalled migration and restructuring attempts.
• a class reference in svn generated from the MediaWiki source code using the Doxygen tool. This documentation can also be generated locally from the MediaWiki source code.
• a handful of architectural, how-to and reference documentation in the /docs directory of MediaWiki’s source tree.

The secondary and supporting resources include blogs, an issue tracker, IRC channels, mailing lists, talk pages and on-wiki or external forums. Additionally, there is some developer documentation that has not yet been migrated from meta.wikimedia.org (see Meta:MetaProject to transfer content to MediaWiki.org).

Experienced community members are accustomed to the complexity of the developer documentation and may know where the right information is located. Various tools (such as mw-bot) and resources (such as various mailing lists) also rely on the current structure, making structural changes a complicated and detail-oriented task.

Newcomers and occasional readers find the developer documentation more difficult to use. Common responses to usage problems include:

• avoiding some or all of the developer documentation
• relying on support channels (like mailing lists or IRC), instead of documentation
• searching via Google, only using the developer documentation as it is related to search results
• using the source code as the primary development reference

Scope

The plan focuses on the MediaWiki developer documentation, along with the issues, groups, processes and tools that relate to the developer documentation.

Principles

The following principles were used to guide the recommendations made in this plan:

• Keep It Simple – choose simplicity over complexity, except in cases where a simple solution isn’t good enough.
• Avoid Change – every change has a cost. Make changes conservatively.
• Don’t Break the Docs – the MediaWiki developer documentation is an important productivity tool for MediaWiki developers. The developer documentation should never be in an unusable or broken state.
• Be Wiki – expect that anyone can participate in the process and that work will be done in a decentralized, transparent and iterative way.
• Decouple Content, Process and Structure – avoid large, complex and monolithic structures and processes. Separate structure and content to allow each to be modified independently. Develop processes that can be broken up into small pieces that can each be worked on separately.
• I Am Not You – the MediaWiki developer community is large and diverse. We need to keep this in mind to avoid making choices that only fit the needs of one particular part of a this larger group.

Stakeholders and Their Interests

Stakeholders are people or groups that have a significant interest in a project. There are two key stakeholders in the MediaWiki developer documentation. Each of these stakeholders has interests that have shaped this plan. The main stakeholders are:

• the MediaWiki Developer Community, a diverse and international community of people who participate in the MediaWiki development process. This community includes paid developers and related staff of the Wikimedia Foundation.
• MediaWiki Adopters, another diverse and international group of people who've chosen to use MediaWiki for public or private needs.

Notes:

Audience for the Plan

The plan is written for the MediaWiki development community and hopes to represent their broad interests. There are several important reasons for this:

• the MediaWiki developer community is the steward of the developer documentation.
• MediaWiki developers developed the current documentation process and authored the current documentation. In the future, it seems certain that they will continue to be the major documentation writers.
• the MediaWiki developer community is also a major stakeholder in the documentation. The accuracy, completeness and usefulness of the documentation strongly affects how effectively people can adopt, use and extend the MediaWiki software.

Roles and Their Tasks / Audiences for the Documentation

People may occupy one or more roles in relation to MediaWiki and the MediaWiki developer documentation. Some key roles include:

• MediaWiki developers who seek to modify or extend MediaWiki.
• MediaWiki extension developers who write MediaWiki extensions using the extension API.
• MediaWiki developer documentation translators who translate the documentation into other languages.

With the exception of the documentation on extensions, the primary audience of the developer documentation is MediaWiki developers. The developer documentation should always be written with the abilities, motives, needs and views of the MediaWiki developers in mind.

Notes:

Goals for the Developer Documentation

• Easy-to-read – the documentation should be easy for the primary audience to skim, read and understand.
• Accurate – the documentation should accurately reflect how the software is intended to work and how it is known to work.
• Practical – the documentation should focus on helping the primary audience effectively solve real problems.
• Complete – the documentation should describe as much of the software as possible and should clearly indicate when something is not documented.
• Inclusive – the documentation may be the first point of contact that a person has with the MediaWiki community and should be accessible, friendly and welcoming.
• Consistent – the documentation should save everyone time and effort by being consistent and predictable.

Goals for the Documentation Process

• Easy-to-implement - the plan has to be implementable by a reasonable number of people working with a reasonable amount of resources (time, money, interest).
• Integrated - the documentation process should be cleanly integrated with the administrative and development processes that it supports.
• Automatable – ...
• Educational - participating in the process should help the participant learn more about technical communication and the topic being documented.
• Inclusive - the process should be welcoming to people who are willing and able to contribute.
• Rewarding - participation in the process should be a rewarding and positive experience. For volunteer contributors, the experience should help them develop professionally or academically.
• Community Development - the overall process should help advance the MediaWiki community.
• Community Engagement - the MediaWiki community should be interested in and willing to work on the documentation and the documentation process.
• Build on Past Effort - there are thousands of hours of effort behind the documentation. The process needs to make sure that we don't discard all of this work while improving the process.
• Provide Secondary Quality Assurance - the process of developing and reviewing documentation can help discover gaps, inconsistencies and errors in the code being documented. We need to ensure that we have good ways to get this information back to the development team.

Process

At the top of this plan, it reads:

This is a plan to improve MediaWiki’s developer documentation by making small, incremental improvements to the existing documentation process and infrastructure.

Supporting this broad statement, we have principles like "Don't Break the Docs", goals for the documentation like "(Be) Practical" and various other pieces of useful contextual information.

To apply all of these ideas, we need a flexible process that balances many different factors but that is still simple to implement and understand. The process also needs to support different kinds of contributors with different skills and skill levels. We want to ensure that people have an easy path with consistent levels of challenge and reward to help keep them engaged. A more complex and monolithic process might be more effective in some circumstances, but in this case would prevent people from participating.

One way to meet these needs is to design a process that consists of many small steps that can be done independently of each other. Each small step should be relatively quick to complete and should improve the documentation in some meaningful way. The steps should move the documentation cleanly from state to improved state. At no point should a visitor come to a page and find that the documentation is less usable that it was a moment ago because someone has been editing it.

Overview

At a very high level, the recommended process has two steps that are repeated over and over:

• Contribute something new or an improvement to a flagged page
• Review contributed work and flag one or more issues with it

The process splits the work of evaluating the documentation from the work of improving the documentation. This split exists because it makes it easier for people to contribute in small, but still meaningful, pieces while they are doing other work. It also allows people to focus solely on tasks that interest them – if someone wishes to only write examples, it should be easy for them to find everything that needs an example.

The brief overview above is very, very abstract. Here's an example of how this could work in practice:

• D. E. Veloper is hacking on the MediaWiki internals and encounters a mysterious global variable called $wgSurprise.
• D. goes to the MediaWiki.org and searches for wgSurprise.
• The search engine returns a few results.
• Looking at the first result, it seems to provide D. with most of the information that they need.
• However, the page has an incomplete summary and doesn't follow the standard template used for global variable reference pages.
• D. flags the page as having a deficiency with its summary and then returns to hacking code. (Note: The flagging could happen via any number of separate mechanisms – let's leave the exact mechanism aside for now.)
• With enough time and interest, D. might have done other bits of work, including:
  • flagged the page for not using the standard template
  • using checklist to see if the page had other issues
  • worked on fixing some of the issues that they encountered
  • fixing that other people have flagged
• Later, another person – Doc Umentor – after looking through a list of flagged pages that need work on their summaries, comes along and improves the summary for wgSurprise.
• When Doc is done with the improvement, he saves the page and removes the flag.

Automated Processes

Some of the work on the documentation should be triggered by automated systems. Examples of when this should happen include:

• new code is committed to the revision control system
• a new issue is added to the issue tracker (or an existing issue changes)
• a new version of MediaWiki is released
• examples (which we plan to treat as a type of unit test) fail to run successfully
• pages are flagged
• users search for a term that isn't found

Active Processes

Some of the work on the documentation should be planned and regularly delivered. Examples of work in this category include:

• development of templates and other resources to support the documentation process
• coverage reviews of key areas (for example, we might want to regularly ensure that the top 25 pages are all of high quality)
• documentation bees or sprints (where teams of contributors work together to rapidly improve the documentation)

Reactive Processes

Some of the work on the documentation should be focused on helping developers with their immediate problems. Examples of work in this category include:

• ensuring that there is documentation relevant to questions asked on support forums
• ensuring that security issues are documented promptly

Raising Awareness

For the process to be successful, it should be fairly well-known by community members. We can raise the visibility of the effort by:

• getting the community engaged with developing the plan
• blog about the work as it progresses and include notes in our weekly reports
• as we get to roll-out, integrate parts of the process into the page chrome, ensuring that readers can easily get more information on the changes to the documentation
• make sure to mention the process when participating in support forums. For example, if you answer a question about a global variable and point someone to the page for the variable in the documentation, mention if you've flagged the page as having some kind of issue.
• teach readers (via support forums and documentation documentation) to use page flags to quickly evaluate the state of a piece of documentation.

Process Flowcharts

Here's a sample flowchart of the basic process of reviewing a page, laid out at as table.

Start: Issue Raised
Does the topic exist?
Yes		No: Flag create
Is it an atomic page?
Yes	No: Flag split
Is it the only page on the topic?
Yes	No: Flag unify
Is the issue covered?
Yes	No: Flag coverage
In the content of high quality?
Yes	No: Flag quality
Is this the only page with this title?
Yes		No: Flag disambiguate
Finish

Notes:

Writing Style

• Write in Plain Language – the documentation should be written using plain language (which includes using simple words, avoiding idiomatic language, and using simple sentences). We can borrow ideas and tools from the Simple English Wikipedia.
• Include Relevant Context – always provide links to foundational concepts and related information. Readers may not find the information that they need on the first try or may not understand the information that they find. Make it easy for them to get to related concepts (for example, a page on regular expressions should also mention str_replace()) and to find prerequisite information (for example, a page on MediaWiki's global variables should include a link to the PHP manual pages on globals).
• Use the Reverse Pyramid Writing Structure – begin with the conclusion or overview of a topic, then add additional detail. This helps readers browse a page faster and easier.
• Use Consistent Document Structure – each page of the same type should have the same structure. Consistent structure helps readers find the relevant information more quickly.
• Use Many Examples – examples provide a concrete instance of the abstract concepts described in the documentation. They also make it easier for people to understand difficult concepts and provide a way for the reader to ensure that they understand the documentation. Further, different people learn in different ways. Some people will always be more comfortable with examples of how something works, rather than descriptions of how something works.
• Write for the Primary Audience – know who you are writing for – who they are, what they know and what they need – and write for them.
• One Point per Paragraph – keep each block on topic. Use whitespace to let the reader know that they are moving from one concept to another.

Documentation Structure

Documentation structure is slightly trickier than writing guidelines. It may be that we will not know what the right structure is until we've been working on the documentation for a while or we've tried a few different structures. Keeping this in mind, we want to bring the documentation into a state that makes it easy to restructure. This means that we want to focus on these things:

• One Topic per Page – Each page should be focused on a particular topic (even if that topic is providing an overview of a variety of related subjects). Where possible, we want to make it clear that there is one place to put, find and update documentation on a given topic.
• Disambiguate – we should adopt a Wikipedia-like approach of using simple titles for pages and then disambiguating as needed. This allows users to browse the documentation in a very natural fashion and quickly move between related concepts with similar names. This has already been done, but not nearly as consistently as is needed. For discussions on this topic, see Thread:User talk:Zakgreant/MediaWiki Technical Documentation Plan/Disambiguate/Flat Namespaces.

In the future, there will be more guidelines to follow on category use, template use and so on. However, we'll need to start the work of revamping the documentation to thoroughly understand how to best manage the structure of the developer documentation.

Risks

There are several key risks related to reworking the MediaWiki documentation process. The ones we should be most concerned with include:

• Contributor alienation – changing processes can make contributors feel like their contributions have not been valued or are now obsolete. We need to make it clear that contributions are valued, contributors are valued and that the process is meant to help (rather than punish or control) contributors.
• Inflexibility – the process will have flaws that are not recognized until it is implemented. We need to make sure that the process fits reality, instead of trying to make reality bend to the process. People who feel a lot of ownership of the plan may be resistant to changes to it (and, often, with good reason). Those of us who work on the plan should be committed to the outcomes of the plan much more than the particular methods used.
• Low adoption – community members may not be aware of or interested in the new process. We must ensure that the community participates in completing this plan and actively work to make people aware of it.
• Overcomplication – the new process may be too "heavy" for contributors to use effectively. We should be prepared to trim off parts that are found to be cumbersome or less useful.
• Small MW.org community - the MW developer community is large, but the number of people actively maintaining MW.org is comparatively tiny. This is not a specific 'risk' as such, but it magnifies all of the above risks, making them more of a problem than they might be on other wikis.

Credits & Sponsors

This work was commissioned by the Wikimedia Foundation. The first draft of the plan was researched and developed by Zak Greant over the summer of 2010 with help from various contributors.

Ariel T. Glenn, Chad Horohoe, Danese Cooper, User:HappyDog, Guillaume Paumier, K. Peachey, Mark Hershberger, Roan Kattouw, Rob Lanphier, Tomasz Finc and Trevor Parscal each provided valuable feedback, as did participants in the Wikimania and WikiSym events.