WMF Projects/Technical Documentation

This is a draft WMF project page for the technical documentation work.

Overview
MediaWiki's documentation is quite useful. Hundreds of people have authored and edited thousands of pages of documentation that cover a significant portion of what is known about MediaWiki. Unfortunately, the documentation varies greatly in accuracy, completeness, content, page structure, translation status, writing style and quality. These inconsistencies makes the documentation hard for many people to use.

Activities for September to December 2010
Over the next few months, technical writer Zak Greant will be focused on helping the community improve MediaWiki's developer documentation, along with the technical documentation processes. During this time, he'll be working on three key things: community engagement, editing, writing and wiki gardening, and testing, collaborating and planning.

Scope
At present, work in this area is focused on the MediaWiki developer documentation. As User:HappyDog notes, all of MediaWiki.org needs to be considered. For the short term, we only have the resources to focus on the developer documentation.

Community engagement
A large part of the documentation work has been done by MediaWiki community members. This project is meant to provide support to them as they continue this work and to provide dedicated resources focused on the documentation.

To help Zak work with the community in ways that follow community norms, he's been doing the following:
 * logging into the relevant IRC channels while working
 * reading and participating in the relevant mailing lists
 * reviewing the Special:OldReviewedPages and Special:RecentChanges lists for MediaWiki.org, editing and approving where possible

To help community members keep up with Zak's activities, he has been:
 * keeping a public todo list at User:Zakgreant/Todo
 * posting daily activity logs (such as User:Zakgreant/Log/2010-10-05)
 * posting weekly reports (such as User:Zakgreant/Report/2010-10-03)
 * holding two IRC office hour sessions (scheduled 12 hours apart, to help accomodate people in a wide range of time zones) per week

Editing, writing and wiki gardening
Zak is spending a good chunk of time writing, editing and structuring the documentation. The work in this areas falls into a few major areas:
 * planned work on specific areas of the documentation (such as a refactoring Security for developers )
 * reactive work like editing Special:OldReviewedPages and Special:RecentChanges lists for MediaWiki.org and ensuring that useful information discussed on the developer mailing lists is migrated into the MediaWiki docs.

This work serves to:
 * improve the documentation
 * help Zak engage with and support the other people working on the docs
 * help Zak learn more about MediaWiki and MediaWiki.org

Testing, collaboration and planning
The long-term goal of the technical documentation work is to significantly improve MediaWiki's documentation and the MediaWiki community's technical documentation process.

So far, we've developed a draft plan for improving MediaWiki's developer documentation. The plan focuses on high-level goals and methods – who are the docs for, what the docs should do for developers and how should they do it, what kind of process should we use to improve the docs, and so on. Read the plan itself at User:Zakgreant/MediaWiki_Technical_Documentation_Plan and see the budding discussions around it at User_talk:Zakgreant/MediaWiki_Technical_Documentation_Plan

The plan is undeveloped in places. We hope to complete the plan through two activities:
 * working with the community to draw in the experience of the folks who've been actively working on the docs for years; and
 * tests that can help us validate (or invalidate) various ideas in the plan (for example, the work on refactoring Security for developers is a test of the ideas in the Documentation Structure section of the plan.)

We've started small. Zak has been testing ideas and talking with people who've noticed him on IRC He hopes to get some of the most active documenters and wiki gardeners reviewing the plan before he asks the broad community to review the plan in earnest.