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

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

Overview

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

Increase developer effectiveness through better technical documentation.
Foster a MediaWiki documenter community.
Increase the number of skilled MediaWiki developers and contributors.

Major Activities

#Identify and improve key documentation – what documentation is most needed and beneficial?
#Automation and integration – make people happy by replacing them with small scripts.
#Community development – helping more people become MediaWiki developers and documenters.
#Measuring progress – doing work in way that is measurable.

Identify and improve key documentation

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

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

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

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

Reduce the effort required
Better integrate resources
Doxygen integrated with MediaWiki.org
API docs integrated with MediaWiki.org (see User:Zakgreant/API docs integration)

Community development

foster volunteer documenters
run hybrid pair doc/office hours
Berlin session
enable contribution

Documenter key needs

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

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

Translation
Staffing

Footnotes

↑ 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.
↑ 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.

[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.

[1]

[2]