User:Waldyrious/Docs

About
Mediawiki documentation is terribly scattered. We have:
 * code comments
 * structured code comments, and corresponding auto-generated docs (see http://doc.wikimedia.org, http://svn.wikimedia.org and proposal to integrate into mw.org)
 * mediawiki pages (manually maintained)
 * the folder
 * some configuration settings described in Extension:Configure
 * message documentation described in the Qqq file
 * english wikipedia
 * others?

Ideally, we should be able to have up-to-date and complete documentation wherever we decide to host it. We need a strategy on where to maintain each type of documentation. Recently I proposed a division of MW documentation into 3 main types: Manual (guides), Tutorial (getting started) and Reference (index). One of the things I'd like to do is move every non-guide-like content into a separate namespace, e.g. Reference, Registry or Index. Here are some external resources suggesting what are the features of good developer documentation (they roughly agree with the overall 3-fold structure suggested above):
 * A proposed structure for API docs organization (image)
 * Roundup: The Best Developer Docs

Related, but less structurally impactful: some years ago there was some discussion about whether to use a flat or nested hierarchy for Manual pages: Project:Manual. My take on this is that we can easily have both, using redirects and disambiguation pages when needed.

Proposed structure
Given the above, I believe the following structure would be encompassing enough to cover most of our docs, and provide a consistent and intuitive top-level navigation system:

In addition, related resources could be listed, namely:
 * Hammer - Noun project 1306.svg &emsp; Interactive tools
 * API Sandbox, eval.php, uselang=qqx, Wikimedia technical search...


 * Comments alt font awesome.svg &emsp; Communication
 * Mailing lists, IRC, Bugzilla, Gerrit...

Manual

 * (very short and incomplete list, basically a few guides that I've found to be well-structured and easy to read)


 * Markup spec -- step-by-step operation of the parser
 * Manual:MediaWiki architecture -- possibly related, I'll have to check to make sure
 * Manual:Parser.php -- also contains parser operation (manual-style), plus a hooks table (reference-like) and getter functions (also reference-like) of the Parser class

Reference

 * See also: Brion Vibber's Modular registry of components -- similar to this list, but more of a wish-list of missing resources

TODO: integrate into table above)

 * Manual:Configuration settings -- list of all configuration settings and a description
 * Manual:LocalSettings.php -- not sure how this differs from the above
 * -- the actual source code.
 * Category:Variables -- might have variables grouped in different (or multiple) ways, possibly useful in addition to the above
 * Manual:Interface/JavaScript -- configuration settings available via javascript
 * -- contains the locations of all MediaWiki classes
 * Manual:Database layout -- db tables + timeline of their existence across MW versions. Also links to db schema diagram
 * Localisation
 * Special:AllMessages -- interface messages
 * Message documentation (qqq)
 * Category:Interface messages -- (very incomplete) documentation
 * [ uselang=qqx] -- appended to any MW page url, it displays message keys rather than their values
 * Manual:Interface/IDs and classes -- CSS IDs and classes (extremely incomplete)
 * w:Wikipedia:Catalogue of CSS classes is more complete, but is polluted by enwiki-specific stuff
 * w:Wikipedia:Catalogue of CSS classes idem
 * w:Wikipedia:Catalogue of CSS classes -- as the name says, CSS and JS files for every skin/browser combination (and some other variables)
 * ResourceLoader/JavaScript Deprecations -- probably relevant to the JS files above
 * Manual:Parameters to index.php -- exactly what the name says :)
 * w:Wikipedia talk:WikiProject Inline Templates/Archive 2 -- a nice list, see if anything (content or design) could be integrated above
 * Extension Matrix -- not really part of mediawiki, but fits with the general index-like nature of the docs listed here
 * Extension Matrix/stable -- only extensions deemed stable
 * Category:Extensions used on Wikimedia and Developers/Maintainers
 * Suggestions for extensions to be merged into core -- extensions distributed with mediawiki's default installer
 * Developers/Maintainers -- components of MediaWiki (name, description, maintainers)
 * maintenance/eval.php -- a tool for interactive experimentation with MediaWiki objects
 * [/api.php API reference] & Category:MediaWiki API Overview
 * Special:ApiSandbox -- an interactive playground to experiment with building and executing API queries
 * Most of the API docs are already reference-like, but this one is particularly neat: API:Database field and API property associations
 * -- not sure it fits a reference-style, gotta check
 * http://svn.wikimedia.org/doc/ -- auto-generated documentation from source code
 * bug #40143 is about doing the same for Javascript, but it hasn't happened yet. Here's an example. Any updates should be placed on Manual:Coding conventions/JavaScript
 * Manual:Coding conventions/PHP -- list of variable prefixes in the PHP code and what they mean
 * w:Help:Cheatsheet -- short list of basic wikitext features
 * Markup spec -- more detailed and technical, but structured in a harder-to-read way
 * Extension:Parser function extensions -- list of parser functions (e.g.  or  ) available in core and in (WMF-enabled? bundled with mediawiki?) extensions
 * Help:Magic words -- details on parser functions built-in on MediaWiki
 * Help:Extension:ParserFunctions -- details on parser functions from Extension:ParserFunctions
 * Help:Magic words -- double-underscore variables, e.g.
 * Help:Magic words -- magic words, e.g.
 * Manual:Hooks & Category:Hooks by file -- what the names say
 * Extension hook registry -- hooks created by extensions
 * -- probably should be synced with the above
 * Manual:User rights -- default user groups and corresponding rights (excerpt from DefaultSettings.php related to $wgGroupPermissions)
 * Manual:User rights -- list of user rights
 * Manual:User rights -- list of user groups
 * Manual:Namespace constants -- mediawiki's default namespaces and corresponding constants
 * Extension default namespaces -- namespaces introduced by extensions
 * Extension:Scribunto/Lua reference manual -- name says all
 * Extension:Scribunto/Victor's API proposal -- proposal for base mediawiki functions in Lua (not sure what's its status: implemented? in progress? abandoned?)
 * Learning Lua from JavaScript#Differences -- differences from Javascript
 * and -- default list of interwiki prefixes
 * -- list of special pages
 * Manual:$wgSpecialPageGroups -- same as above, sorted into groups
 * Special:SpecialPages -- same as above, but only complete if you hold all user rights
 * meta:Help:Special page -- has some documentation (brief description of what each page does), but with a somewhat loose structure