WMF Projects/Technical Documentation

Wikimedia Foundation projects Technical Documentation Improve MediaWiki's technical documentation by making small, incremental improvements to the docs and the docs process. Team members: Rob Lanphier, Zak Greant

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 to use and maintain.

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, the Wikimedia Foundation has only set aside 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 the community 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 accommodate 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.

With input from various contributors, Zak's 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 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. Zak hopes to complete the plan through two activities:

• working with the community to draw on 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.