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 develop and deploy a robust technical documentation process for use within WikiMedia community projects. The plan focuses on the MediaWiki developer documentation and the Wikipedia technical operations documentation, but is designed to be easy for other projects to modify and use. =Summary = The core recommendation ...

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 with help from various contributors. A timeline of activities can be found in the appendices.

= Goals =

Documentation Goals
The most important goal of this plan is to produce high-quality documentation that has following characteristics: Notes:
 * Easy-to-read - the documentation should be easy for the intended audience skim, read and understand.
 * Accurate
 * Complete
 * 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 modify and use the plan 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).
 * Integrated - the documentation process should be cleanly integrated with the administrative and development processes that it supports.
 * 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.

Process

 * why have a process
 * what is the process?

Overview

 * provide high-level overview of the process(es) behind creating, reviewing and archiving documentation
 * provide use cases that drive the creation or editing of docs
 * planned coverage
 * new code written
 * bug confirmed
 * code modified
 * support question asked
 * documentation outdated
 * tests fail
 * infrastructure change
 * hosting emergency

Priorities

 * set priorities based on goals
 * correlate to use cases


 * 1) Wikipedia hosting issue takes top priority
 * 2) coverage - fixed time each day
 * 3) requests - fixed time each day
 * 4) events - fixed time each day

Tools

 * outline tools to help automate and improve process
 * cover both mediawiki

Integrating with the MediaWiki Development Process

 * outline desired MediaWiki development process (coord with team leads and pms here)
 * note hooks in docs

Use Cases
... turn triggers into use cases ...

Documenting on Request

 * process for different types of documentation
 * how-to
 * policy
 * reference

Recommended Process for Deployment
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.

Editing Recommendations

 * work towards simplicity
 * we'll need to collect these over time
 * we'll need to collect these over time

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 requirements. More permissive?

Recommendations for Code Examples

 * versioned
 * used as part of test suite
 * maintained in revision control system
 * automatically correlated to docs
 * user contrib can live in other space -> rolled into revision control system after review

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

Personas

 * split off into separate, templated documents

MediaWiki Sysadmins
tasked with installing, maintaining and sometimes patching mw

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

MediaWiki Forkers
developers working on public or private forks of MediaWiki

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

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.

Credits
=Todo= ...
 * Add topics for MediaWiki Developer Docs and Wikipedia Technical Operations Docs

Interview MediaWiki Technical Management and Dev Team Leads
Interview members of technical team responsible for high-level planning about the desired MediaWiki development process and the current transitional state:
 * Danese Cooper
 * Rob Lanphier
 * Tim Starling
 * Tomasz Finc

Interview Mediawiki Technical Ops Team

 * Ariel Glenn
 * Domas Mituzas
 * Fred Vassard
 * Jens Frank
 * Mark Bergsma
 * River Tarnell
 * Roan Kattouw
 * Rob Halsell
 * Tim Starling
 * Tomasz Finc