User:Zakgreant/MediaWiki Technical Documentation Plan

This document is in the process of being expanded and converted to MediaWiki format. As such, it may be varying degrees of ugly, incomplete, incoherent or otherwise broken. Still, please feel free to review. If you have comments or wish to discuss, please catch me on IRC (zakg on irc://freenode#mediawikia) or via email [mailto:zak+mediawiki@fooassociates.com zak+mediawiki@fooassociates.com] DRAFT // Last Updated: MediaWiki Technical Documentation Plan

This is a plan to improve MediaWiki’s developer documentation by making small, incremental changes to the existing documentation process working with the existing 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.

The 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 that focuses on how-to documentation and reference materials. This documentation is a part of mediawiki.org and can be browsed at http://www.mediawiki.org/wiki/Manual. 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 generated from the MediaWiki source code using the Doxygen tool. This documentation can be browsed online at http://svn.wikimedia.org/doc or can be generated from the MediaWiki source code using Doxygen.
 * a handful of architectural, how-to and reference documentation in the /docs directory of MediaWiki’s source tree. The current version of these materials can be viewed online at http://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/docs.

The secondary and supporting resources include blogs, an issue tracker, IRC channels, mailing lists, talk pages and in-wiki forums. Additionally, there is some developer documentation that has not yet been migrated from http://meta.wikimedia.org.

Experienced community members are accustomed to the complexity of the developer documentation and may know where the right information is located. Various tools and resources 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.
 * 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 three 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.
 * 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 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.

The WikiMedia Foundation is another important audience. Like the MediaWiki developer community, they are a key stakeholder for the project. They also serve as the sponsor for this plan, paying for and facilitating it’s development.

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 that 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 skim, read and understand.
 * Accurate – the documentation should accurately reflect the how the software is intended to work and how it is known to work.
 * Practical – the documentation should focus 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 a WikiMedia 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 WikiMedia communities.
 * Community Engagement - the WikiMedia community should be interested in and willing to work on the documentation and the documentation process. faith valuable
 * 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.

Writing Style

 * Write in Plain Language –
 * Include Relevant Context –
 * Use the Reverse Pyramid Writing Structure –
 * Write for the Primary Audience –
 * One Point per Block –

Documentation Structure

 * 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.
 * Consistent Page Structure –
 * Flat Namespaces –
 * Disambiguate –
 * Consistent Category Use -

Risks
...
 * Community Alienation –
 * Inflexibility –
 * Low Adoption –
 * Overcomplication –

Credits & Sponsors
This work was commissioned by the WikiMedia Foundation. The plan was researched and developed by Zak Greant (User:Zakgreant) over the summer of 2010 with help from various contributors. Ariel T. Glenn, Danese Cooper, Mark Hershberger, Roan Kattouw, Rob Lanphier, Tomasz Finc and Trevor Parscal all provided valuable feedback, as did many participants in the WikiMania and WikiSym events.