Jump to content

User:Waldyrious/Docs

From mediawiki.org

About

[edit]

MediaWiki documentation is not only infamously incomplete, but also terribly scattered. We have:

  • code comments
  • structured code comments, and corresponding auto-generated docs
    • Note from Jan 2023: the auto-generated docs used to be published for both PHP and JS, but since 1.35 only the JS version has been published in the tagged versions listed in that page. That said, the PHP docs are still present in the REL1_XX versions (example for 1.35) as well as in the master version. This may be an unintentional issue.
  • MediaWiki pages (manually maintained)
  • the docs folder
  • some configuration settings described in Extension:Configure
  • message documentation described in the MessagesQqq.php file
  • English Wikipedia
  • Likely 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. For more details, I've collected some external resources about good documentation and how to structure them, in this google doc.

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#Structure. 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.

Like-minded initiatives in the community:

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

[edit]

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.

On the first axis, we would have reader profiles:

 [[   User
Doesn't have access to the server hosting their wiki, but wants to get the most out of mediawiki, and does so by editing interface messages, tweaking javascript/css files, building templates, and using mediawiki features such as parser functions, magic words, the API and special pages.
 $>   System Administrator
Has access to the server and can install mediawiki and extensions, perform configuration changes, run maintenance scripts, change the database and php files, etc.
 {}   Developer
Wants to contribute to the canonical mediawiki software, so that others can benefit from the improvements. Submits patches to core and/or extensions, and generally needs to understand how mediawiki works under the hood.

On the second axis, we would have the type of documentation:

    Tutorial
Step-by-step instructions for executing specific tasks, solving real-world needs, with code examples.
→ Example: Gerrit/Getting started
   Manual
Comprehensive, narrative-like documents that describe high-level, fairly self-contained subsystems of the mediawiki infrastructure. Useful for in-depth learning about those subsystems and getting a good overview of their working.
→ Example: Manual:Messages API
    Reference
Comprehensive, index-like documentation (potentially auto-generated or auto-aggregated), optimized for locating information on a specific element of a system and quickly studying its relevant properties. Each entry should be short and concise.
→ Example: Manual:Configuration settings
    Interactive tools
Tools that allow experimenting and exploring the available resources in a non-destructive environment.
→ Example: API Sandbox
    Communication
Channels for communicating directly with other humans and get one's questions answered in a more personalized way.
→ Example: IRC
Finally, on the third axis, we'd organize documentation by category. Currently there's no accepted ontology to cover all things MediaWiki, but here are a few useful resources to assist in building one:

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:

  • 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
      • ...

...where only the leaf categories would be added to each page.

Overview of existing resources

[edit]

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.

Tutorial

[edit]
 Tutorial-type documentation resources
[[ For Users $> For System Administrators {} For Developers
Topic Generic
PHP Classes
Extensions
JavaScript
CSS
Database
Interface messages
API
Wikitext
Hooks
User rights and groups
Namespaces
Maintenance scipts
Special pages
Internationalization

Manual

[edit]
 Manual-type documentation resources
[[ For Users $> For System Administrators {} For Developers
Topic Generic
PHP Classes
Extensions
JavaScript
CSS
Database
Interface messages
API
Wikitext
Hooks
User rights and groups
Namespaces
Maintenance scipts
Special pages
Internationalization

Reference

[edit]
 Reference-type documentation resources
[[ For Users $> For System Administrators {} For Developers
Topic Generic
PHP Classes
Extensions
JavaScript
CSS
Database
  • Manual:Database layout -- db tables + timeline of their existence across MW versions. Also links to db schema diagram
Interface messages
API
Wikitext
Hooks
User rights and groups
Namespaces
Maintenance scipts
Special pages
Internationalization
  1. ↑ A bunch of information was removed from this page in Special:Diff/3650490

Unsorted

[edit]

Interactive tools

[edit]

Communication

[edit]
Retrieved from "https://www.mediawiki.org/w/index.php?title=User:Waldyrious/Docs&oldid=5747667"