User:TBurmeister (WMF)/Sandbox/Collections

This page gathers ideas and strategies around how to group technical documentation into meaningful units that facilitate browsing, discovery, and maintenance. In Q1 of FY22-23 we are investigating: "What strategies or tools have people used, considered or suggested to identify sets of related docs or divide up the content space?" This is part of work on phab:T313037.

How do we define the collections?
Different organizing principles currently exist, and others have been suggested in brainstorming sessions or other feedback channels. Documents are related to each other in multiple, varied ways:

How do we indicate and track which content is in which collections?
This is a survey of current practices, not (yet) a recommendation for what we should do.

Document metadata
Metadata can be embedded in a page name or added to a page in a variety of ways. People often use these different types of metadata to create connections between related content:

Navigation templates or navboxes
Examples:


 * https://wikitech.wikimedia.org/wiki/Wikimedia_infrastructure
 * Template:Huggle/DocHeader
 * Template:Installation Guides
 * Template:OOUI
 * ..More examples

Some navigation templates group together pages that *mostly* share a hierarchy or namespace, but navigation templates usually include at least some pages that reside outside of the canonical page hierarchy or namespace for a given topic. Especially because namespaces exist to cover different facets of the same topic (like Help:, API:, and Manual:), navigation templates often serve to provide paths between these namespaces. For example: the VisualEditor navigation template includes links to pages following the page hierarchy pattern, but also.

Link hubs and lists of docs
This approach is similar to a navigation template, but the lists of docs are usually longer or specially formatted as a link hub or doc portal, and not transcluded anywhere -- they only live in this one location. Transcluding the pages automatically listed by Special:PrefixIndex makes it possible to auto-generate a list of subpages, but that can get noisy and doesn't list the content in a meaningful way. Long lists of links don't really help anyone.

Manually-curated examples:


 * https://meta.wikimedia.org/wiki/Small_wiki_toolkits
 * Developer hub
 * Developer portal - consider each site section as a "collection"
 * https://meta.wikimedia.org/wiki/Data_dumps
 * Wikibase
 * Product Analytics

Examples using Special:PrefixIndex:


 * Continuous integration

Web domains

 * "We do separate doc locations a bit on audience, wikitech used for services, wikitech more internal in terms of audience, mw.org very broad scope"
 * "Following is a list of the main places to find Wikimedia technical documentation.
 * MediaWiki - MediaWiki software documentation and technical documentation for many other Wikimedia technology projects. This is the default space for publishing technical documents about Wikimedia technology.
 * Wikitech - Technical documentation for Wikimedia Foundation infrastructure and services. This includes production clusters, Wikimedia Cloud Services, Toolforge hosting, the Beta Cluster, and other data services.
 * Wikidata - Technical documentation related to the Wikidata project, particularly the Tools page.
 * PAWS - Documentation about PAWS, Wikimedia's hosted Jupyter notebooks instance. Notebooks are frequently used to create tutorials and documentation for Wikimedia technology.
 * Phabricator - Phabricator is a collaboration tool that is used by the Wikimedia technical community for task and bug management. You can find many issues and software projects documented here. Use best practices for software documentation when filing tasks and interacting in this space."

Community suggestions and prior art

 * Add Tags to docs - like labels