User:Zakgreant/WikiMedia Documentation Plan

DRAFT // Revision: // 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:
 * the MediaWiki developer documentation; and
 * the Wikipedia technical operations manual.

=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. 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 scan, 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.

Licensing Recommendations
=Writing Samples= = Appendices =