User:Zakgreant/DeveloperDocs

DRAFT / UPDATED -00-

Location
Where are the developer docs (and related resources) located?
 * the Technical Manual lives at http://www.mediawiki.org/wiki/Manual:Contents (and has a three-year-old todo page at http://www.mediawiki.org/wiki/Manual:Contents/To_do)
 * How_to_become_a_MediaWiki_hacker contains links to other docs (but needs polishing.)
 * the FAQ (which focused on administration issues) lives at http://www.mediawiki.org/wiki/Manual:FAQ
 * there are various points of contact for dev issues at http://www.mediawiki.org/wiki/Communication and http://www.mediawiki.org/wiki/Project:Support_desk
 * the /docs directory in the source
 * the doxygen-generated docs from the source comments (see the built instructions in http://svn.wikimedia.org/svnroot/mediawiki/trunk/phase3/docs/html/README and the usage note at http://www.mediawiki.org/wiki/Manual:Coding_conventions#Inline_documentation)
 * the HISTORY, INSTALLATION, README, RELEASE-NOTES and UPGRADE files in the source can be a good resource for cross-referencing other docs (and should be kept in sync with other docs. In fact, we'll need to understand/decide how these resources fit together.) Also, README and INSTALL haven't been updated in over 18 months – perhaps they need a review?

Additional resources

 * the Wikimedia Technical Blog (http://techblog.wikimedia.org)
 * the code review system at http://www.mediawiki.org/wiki/Special:Code/MediaWiki (with usage notes at http://www.mediawiki.org/wiki/Code_review)
 * the MediaWiki Development category (http://www.mediawiki.org/wiki/Category:MediaWiki_Development)

Policies

 * what policies are in place for the docs?
 * how relevant are they?
 * are they followed?

Completeness

 * How complete is the existing documentation?
 * by feature?
 * source code comments by function / constant / public var?
 * How up-to-date is the existing documentation?

Notes:
 * what tools exist (if any) to assist with this?

Audience

 * Which audiences are the docs written for? Is there an explicit choice of who to write for?
 * Which audiences should the docs be written for?
 * What concerns do these audiences have?
 * Do the docs meet audience needs?

Usability

 * How easy are the docs to use?
 * How easy are the docs to update?

Community

 * What ongoing community efforts exist to extend/maintain/refactor the documentation?
 * Is there a documentation community? Who are the key participants?
 * What support does the community need?
 * What are their goals?

Resources

 * existing docs
 * mailing lists
 * source code
 * input from the docs community
 * traffic logs