Jump to content

User:Zakgreant/Tech Docs Plan (2011-01/P6M)

From mediawiki.org

This is a draft plan for work on the MediaWiki technical documentation for the first six months of 2011. Please review and comment.

Overview

[edit]

With the current number of documenters, the MediaWiki technical documentation is too large to manage as a whole. We can deal with this problem of scale by:

  • developing a larger documenter community.
  • focusing our current resources on the most critical needs.
  • automating work where possible.

Goals

[edit]
  1. Increase developer effectiveness through better technical documentation.
  2. Foster a MediaWiki documenter community.
  3. Increase the number of skilled MediaWiki developers and contributors.

Major Activities

[edit]

Identify and improve key documentation

[edit]

We should focus our effort on improving the documentation that most affects our goals, keeping in mind that we are serving two distinctly different groups:

  • non-developers who want to become developers
  • developers who want to work on and with MediaWiki

Sprints

[edit]

We should divide work in these areas into roughly eight day sprints over a two week period.

  • Announce – Let folks know what we're working on. Ask for help identifying existing articles, needs and resources.
  • Discover – Spend a few hours looking for existing articles, needs and resources related to the work. Quickly outline the scope of the work.
  • Work – Spent about eight days writing, editing, consolidating, expanding, deleting, etc. Set up pair documentation sessions. Post difficult issues to #mediawiki or the developers list.
  • Report – Write a brief report of what was done and post to the tech blog and dev list. Make sure to call out who helped.

Novice key needs

[edit]

Novices need solid introductory materials to help them quickly see real results. I think that five very important areas include:

  • An introduction to MediaWiki development that helps get novices started down the right path. For example: Web users without programming experience need to be sent to good programming and PHP tutorials, while novice PHP developers need to be directed to tutorials that help them apply their skills to MediaWiki. How to become a MediaWiki hacker is meant to fulfill this role, but currently fall short in several key areas.
  • An API tutorial meant for MediaWiki power users [1] and a general edit on related materials.
  • An extension-development tutorial that focuses on basic tasks and a general edit on related materials.
  • A guide to elementary PHP/MediaWiki troubleshooting and a general edit on related materials.
  • A tutorial to writing unit tests and a general edit on the unit testing materials.

Developer key needs

[edit]

Developers need materials that help them avoid needless work.[2]

  • A solid overview of the MediaWiki development process and key articles and a general edit on related materials. The developer hub is clearly the main document in this area.
  • Better core reference docs. We need to improve the documentation that covers the MediaWiki code. Work in this area should include integrating the source code level documentation into MediaWiki.org (instead of having it be a separate, hard-to-use resource.)
  • Better guides to unit testing and Selenium testing.
  • Better policy and process documents that outline what the developers do at release time, on finding a security issue, etc.
  • Better MediaWiki security documentation. Despite having Security for developers and friends, there is still much work to do around helping MediaWiki developers code around security issues.

Automation and integration

[edit]

Community development

[edit]
  • foster volunteer documenters
  • run hybrid pair doc/office hours
  • Berlin session
  • enable contribution

Documenter key needs

[edit]
  • Clear lists of rewarding tasks to work on. This can be facilitated with lists of pages that need improvement and important activities to undertake. These lists will also reduce documenter anxiety (that nagging feeling of, "Am I working on something needed? Will my work be valued? Et cetera.")
  • A style guide to help increase quality and coherency.
  • Community support. Documenters need to feel that they are a part of the community and that their work is valued.
  • Mentoring

Measuring progress

[edit]
  • metrics resources are stretched thin right now
  • focus on:
    • meeting objectives set in plan
    • anecdotal evidence (that is, are the devs other stakeholders happy with the work)
  • do interviews / light usability testing
  • look at #mediawiki
    • look for topics
    • look for usage patterns
  • show diffs
  • look at edit counts
    • new editors
    • edit count changes in existing contributors
  • gather stats on wiki edits
    • consolidation
  • page lifetime
  • identify duplicates

Misc. Issues

[edit]
  • Translation
  • Staffing

Footnotes

[edit]
  1. MediaWiki power users may have a few programming skills (or may not), but definitely are not programmers yet. However, they have many of the foundation skills needed to become a MediaWiki programmer – such as a good knowledge of how the web and MediaWiki work, basic HTML skills, good online communication skills, etc.
  2. Examples of needless work include writing code that's already been written, reading the source for code that's been documented, relying on inaccurate documentation, etc.