User:Waldyrious/Docs

About
Mediawiki documentation is not only infamously incomplete, but also 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 (prose/overview), Tutorial (step by step) and Reference (index-like). One of the things I'd like to do is move every non-guide-like content into a separate namespace, e.g. Reference. 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).
 * Comment on HN about what info a usable website landing page should provide.
 * http://apidocjs.com/ - a standard? how disseminated is it?

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.

Likeminded initiatives in the community:
 * User:Zakgreant/MediaWiki Technical Documentation Plan
 * 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
 * Zurich Hackathon etherpad: http://etherpad.wikimedia.org/p/wddh (by Moiz Syed et. al)
 * 65074: Set up dev.wikimedia.org portal

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 structure described in the table below would be encompassing enough to cover most of our docs, and provide a consistent and intuitive top-level navigation system.

Since this is a three-axis structure, it would probably be best implemented using categories, with portals for each of the axes (with some manually curated text and also automatic lists using Extension:CategoryTree and/or Extension:DynamicPageList) so readers can browse by the criteria that makes more sense to them. So we'd have a category hierarchy like: ...where only the leaf categories would be added to each page.
 * MediaWiki documentation
 * by reader type
 * User
 * Sysadmin
 * Developer
 * by documentation type
 * Tutorial
 * Manual
 * Reference
 * Interactive tools
 * Communication (this would of course have other parent categories, not only the documentation one)
 * by topic
 * Classes
 * Extensions
 * Parser
 * Database

Overview of existing resources
NOTE: it would probably make more sense for a complete listing to be sorted by topic. Documentation type and reader type are secondary attributes (this is how many of the disambiguation pages work already). For now, the division as presented below is the most useful in order to identify gaps in documentation (and pages in need to be merged), but after the survey is complete, the user-facing documentation portal should be build using topics as the main organization unit. In fact, maybe we could even prepare a template for disambiguation pages, and the doc portal would consist mostly (apart from a header and footer) of transcluded disambiguation pages.

Unsorted

 * 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
 * List of Wikimedia Data Dumps on Meta: https://meta.wikimedia.org/wiki/Data_dumps

Interactive tools

 * Sandbox pages, mySandbox gadget
 * API Sandbox
 * eval.php
 * uselang=qqx
 * Wikimedia technical search

Communication

 * Mailing lists
 * IRC
 * Talk pages
 * Technical Village pumps
 * Bugzilla
 * Gerrit
 * Hackathons and other events