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 and by hiring additional documenters.
 * focusing our current resources on the most critical needs.
 * automating work where possible.

{|
 * valign="top" style="border-right: 1px solid #AAA; padding-right: 2em;" |
 * valign="top" style="border-right: 1px solid #AAA; padding-right: 2em;" |

Goals

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


 * valign="top" style="padding-left: 2em;" |

Major Activities

 *  – what documentation is most needed and beneficial?
 *  – make people happy by replacing them with small scripts.
 *  – helping more people become MediaWiki developers and documenters.
 *  – 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 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.
 * 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

 * Choose a limited scope for activity (like the key needs above)
 * good enough
 * simple user-level article metrics/mini-surveys
 * discuss key metrics with Eric Z. and others. What do we measure and what could we measure.  I don't want to try and d
 * possible good metrics
 * number of new editors on MediaWiki.org
 * increased activity of existing editors
 * links from third-party site

Misc. Issues

 * Translation
 * Staffing