WMF Projects/Technical Documentation

From MediaWiki.org
Jump to navigation Jump to search

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

Overview[edit]

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[edit]

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[edit]

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[edit]

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:

To help community members keep up with Zak's activities, he has been:

Editing, writing and wiki gardening[edit]

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:

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[edit]

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 [3] 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[4] 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.

Notes[edit]

  1. including #mediawiki, #mediawiki-i18n, a private channel to discuss security topics, #wikimedia, #wikimedia-dev and #wikimedia-tech.
  2. including mediawiki-api, mediawiki-l and wikitech-l.
  3. 3.0 3.1 see User:Zakgreant/Security for developers, along with CSRF. Register globals, SQL injection and XSS, to review the work done.
  4. either when he is hanging out or via his office hours sessions), the mailing lists or via his work on MediaWiki.org.