User:Zakgreant/WikiMedia 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] INCOMPLETE DRAFT // Last Updated: WikiMedia Documentation Plan This is a plan to deploy a robust technical documentation process at the WikiMedia Foundation.

This first draft is focused on two key areas: =Summary = The core recommendation ...
 * the MediaWiki developer documentation; and
 * the Wikipedia technical operations manual.

One paragraph summary ...

This work was commissioned by the WikiMedia Foundation. The plan was researched and developed by Zak Greant  over the summer of 2010. A timeline of activities can be found in the appendices.

= Goals = The most important goal of this plan is to produce high-quality documentation with the following characteristics: Notes:
 * Easy-to-read - the documentation should be easy for the intended audience skim, read and understand.
 * Accurate
 * Usable
 * Re-usable - the documentation should be written and structured to allow easy re-use and re-factoring. Other projects inside and outside of the WikiMedia community should easily be able to use the documents for their own purposes.
 * Up-to-date
 * Practical - the documentation should focus on real situations that matter to the intended audience.
 * Result-oriented - the documentation should help the intended audience complete tasks that matter to them.
 * Easy-to-translate
 * Easy-to-maintain
 * International - the documentation should be easy for non-native English speakers to understand.
 *  Inclusive - the documentation may be the first point of contact that a person has with a WikiMedia community and should be friendly and welcoming to all.
 * versioned - each major release of MediaWiki should be supported with a version of the documentation.
 * Make Development Easier - for the MediaWiki developer documentation, the primary goal is to make developing with and on MediaWiki easier.
 * Robust Wikipedia - for the Wikipedia technical operations, the primary goal is to have a stable, secure and robust Wikipedia.

Goals for the Documentation Process
The process of producing the documentation should also have specific goals: Notes: =Recommendations=
 * 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).
 * 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.
 * 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 thing being documented. We need to ensure that we have good ways to get this information to the relevant teams.

Recommended Process
The plan should be worked on in five major steps. At each step along the way, the plan is revised as needed. Roughly, the steps are:
 * 1) Review: Stakeholders (like the development community and WikiMedia Foundation) review the plan and give their input. The documentation team will then revise the plan and engage the stakeholders in further review, if the review is needed.
 * 2) Test: The  documentation team test the plan by developing the smallest meaningful implementation of each major part of the plan. In practical terms, this will means setting up MediaWiki instances, documenting a fragment of most major parts of MediaWiki, working together with developers and sysadmins to synch up the admin, development and documentation processes, etc. The tests will build the skill of the documentation team and will help refine the plan by identifying additional solutions, needs and issues. Once the stakeholders and documentation team are satisfied with the results from testing, the next stage can begin.
 * 3) Deploy: The documentation team builds the plan.
 * 4) Migrate: Once the new documentation systems reasonably complete, all existing resources will be redirected as appropriate to the new documentation.  Deploy and migrate are presented as separate steps, so as to reduce the problem of fragmenting information across many separately-updatable resources (such as has happened with the MediaWiki developers documentation, which is documented in multiple places that are haphazardly updated.)
 * 5) Continuous Integration: ....

In more detail, the steps are:

1. Stakeholder Review of Plan
...
 * Goals for Stakeholder Review:
 * Identify Stakeholders:
 * Engage Stakeholders:
 * Gather Stakeholder Feedback:
 * Open-ended Feedback:
 * Guided Feedback:
 * Revise Plan:
 * Repeat as Needed:

2. Public "Spike" Iteration

 * Identify Smallest Meaningful Implementation:
 * Test:
 * Implement:
 * Revise Plan:
 * Repeat:

Meta-Process
At each stage in the process, we want to keep the following principles in mind:
 * Collaborative:
 * Flexible:
 * Open:
 * Service-oriented:

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.

Include Relevant Context

 * ... for Artifacts:
 * ... for Processes:

Write Using the $NAME Voice
We may need to develop a voice for the MediaWiki docs. Alternately, we may find that a few little expansions to these guidelines are sufficient.

Recommendations for How-to Documents
...

Page Structure

 * Header:
 * Audience(s):
 * Topic(s):
 * Summary:
 * Body:
 * Exposition:
 * Examples:
 * Illustrative:
 * Useful:
 * Footer:
 * See Also:
 * Categories:

Recommendations for Policy Documents
...

Recommendations for Reference Documents
...

Licensing for WikiMedia Project Documentation
Use simple, permissive licensing - or a public domain grant requirement - to avoid problems such as were encountered with the license migration on Wikipedia. ... expand this section? may not be needed, as the issue should have already been discussed at great length. Ping Godwin?

Minimal Contributor Licensing Agreement
...

Licensing for this Document
(c) 2010 WikiMedia Foundation Licensed as per terms of MediaWiki.org licensing requirments. More permissive?

Recommendations for Examples
...

Example Structure

 * Title:
 * Summary:
 * Tested with:
 * Code/Instructions':'

Testing

 * Manual v. Automatic
 * Test profiles

Versioning and Test Profiles
Special:Version write extension to display this info in a convenient string?

Example Licensing
= Appendices =
 * allow broad re-use

Research
See CONTRIBUTORS in source

List of Documentation Sources
http://www.mediawiki.org/wiki/Manual:Contents http://www.mediawiki.org/wiki/Manual:FAQ http://meta.wikimedia.org/wiki/Help:Administrator%27s_Guide outdated http://www.mediawiki.org/wiki/Sysadmin_hub http://www.mediawiki.org/wiki/Help:Contents http://www.mediawiki.org/wiki/Manual:Contents http://meta.wikimedia.org/wiki/Help:Contents FAQ file in root points to http://www.mediawiki.org/wiki/Manual:FAQ
 * Doxygen
 * Source Code

Needs to coordinate with online install docs http://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/docs/

List of Support Resources
site admin support development

http://www.mediawiki.org/wiki/Project:Support_desk

https://bugzilla.wikimedia.org/

http://www.mwusers.com/forums/content.php http://www.facebook.com/#!/group.php?gid=2205099323

Samples
Link to separate document.

Sysadmins
tasked with installing, maintaining and sometimes patching mw

Developers
tasked with hacking and extending mw native v. non-native FLOSS dev?