User:Waldyrious/Docs

About
Mediawiki documentation is terribly scattered. We have:
 * code comments
 * structured code comments, and corresponding auto-generated docs
 * mediawiki pages (manually maintained)
 * the folder
 * some configuration settings described in Extension:Configure
 * message documentation described in the 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
 * Beautiful Docs - a compilation of well-written, well-structured, and visually pleasing docs
 * Designing Great API Docs - lots of good advice and examples. includes a similar categorization as the one proposed below.
 * How I Judge the Quality of Documentation in 30 Seconds - A Website (not a directory full of files on GitHub), Prose (not merely generated from source code), URLs (Versions, Language, Permalinks).

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.

TODO: read Technical communications/Dev wiki consolidation and integrate ideas here as fit. See also this thread.

Lots of energy lately concerning this. See:
 * User:Yuvipanda/whatcanidoforwikipedia.org
 * MZMcBride's proposal for a developers.wikimedia.org
 * Get involved (mockup)
 * How to contribute
 * Project:New contributors/One ontology (split from the link in the TODO above)
 * User:Krinkle/Content structure, Thread:Project:Current issues/Restructure MediaWiki.org (or: Document how it was and execute it) and Requests for comment/Documentation overhaul

Summana suggested on IRC to "ask User:KatieIreneC and Yury Katkov what they think about the developer profiles categorization; they are an education researcher (studying how people learn tech skills) and a MediaWiki enterprise community shepherd, respectively". She also mentioned this link which offers a different categorization (systematic, pragmatic and oportunistic). I intend to analize that and hopefully come up with better terms and a more systematic description (e.g an axis-based system where people can be put according to whether they exhibit more or less of the traits the axes describe).

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://doc.wikimedia.org -- auto-generated documentation from source code
 * Since bug #40143 it now contains Javascript docs too (core, VisualEditor). Todo: make sure this is noted on Manual:Coding conventions/JavaScript
 * It would be nice to reduce duplication by transcluding auto-generated docs to mediawiki pages (e.g. Manual:Skin.php vs Skin_8php.html). Allowing regular users to contribute to the docs could be done by having them comment on the talk page, and transcluding the talk page to the main page, for increased visibility (like is done in explainxkcd.com)
 * proposal to integrate into mw.org (wikitech-l message)
 * bug 46526 - System documentation integrated in source code
 * Mentorship programs/Possible projects
 * 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
 * Category:New contributors