Documentation/Documentation types

This page contains research and notes on the idea of managing Wikimedia documentation pages by type. Feel free to add your ideas to this page or the talk page.

Scope

 * In scope:
 * Wikimedia technical documentation
 * documentation about collaboration and processes for Wikimedia technical projects
 * documentation about collaboration and processes for Wikimedia content projects
 * Out of scope:
 * wikimediafoundation.org
 * legal documentation
 * project content, like Wikipedia articles and Wiktionary entries
 * web apps
 * blog posts

Terms

 * content type
 * the structure and goal of a documentation page

Key doc review process
2021-2022

From Documentation/Review_template:


 * Landing page: Landing pages are link hubs that help the reader find information. Landing pages are navigation oriented.
 * Cross-collection landing page
 * How-to guide: How-to guides are directions that take the reader through the steps required to solve a real-world problem. How-to guides are goal oriented.
 * Tutorial: Tutorials are lessons that take the reader by the hand through a series of steps to complete a project. Tutorials are learning oriented.
 * Explanation: Explanations are discussions that clarify and illuminate a particular topic. Explanations are understanding oriented.
 * Reference: References are technical descriptions of a system and how to operate it. Reference documentation is information oriented

Audit of key technical docs
2021-2022

From spreadsheet (restricted access):


 * web app
 * blog post
 * code repository
 * contributing guide
 * explanation
 * how-to guide
 * landing page
 * readme
 * tutorial
 * overview
 * guidelines
 * metrics dashboard
 * portal
 * process description
 * team page
 * user group page

Documentation/Patterns
2022


 * Documentation/Patterns/How-to guide
 * Documentation/Patterns/Landing page
 * Documentation/Patterns/Tutorial

Documentation/Toolkit
2022

Documentation/Toolkit


 * Documentation/Patterns/Landing_page
 * Documentation/Patterns/Tutorial
 * Documentation/Library_Documentation_Template
 * Documentation/How-to_template
 * Documentation/API_Documentation_Template

List of content types
This is an uncurated list of content types with notes, examples, and related links.


 * landing page
 * Documentation/Patterns/Landing_page
 * tutorial
 * Working page: Documentation/Patterns/Tutorial
 * how-to guide
 * Documentation/Patterns/How-to guide
 * Documentation/How-to template
 * wikitech:Category:How-To
 * quickstart guide
 * contributing guide
 * explanation
 * reference
 * archived page
 * guideline
 * meta:Category:Meta-Wiki_guidelines
 * sandbox
 * list
 * FAQ
 * readme
 * overview
 * guidelines
 * metrics dashboard
 * portal
 * process description
 * project page
 * Wikimedia_Product_Guidance/Starting_a_project_page
 * team page
 * talk page
 * user group page
 * sprint tracker
 * Wikimedia_Release_Engineering_Team/Sprint/GitLab-a-thon-ii-wrath-of-kahn

Cataloging docs
How can we track documentation pages by content type?

Categories
For documentation on wiki, we can use categories, such as Category:Tutorials to indicate and track content types.

In order for this strategy to be effective, obsolete or historical pages must not be included in these categories. Based on Project:Schools of thought on deletion, removing categories from obsolete pages could be a good compromise between inclusionism and deletionism. Categories can act as part of the curation layer, while historical pages can still be accessed via search. As of April 2023, there are several obsolete or historical pages included in Category:Tutorials.

Alternatively, we could find a way to search for pages in a content-type category but not in Category:Outdated pages or Category:Pages kept for historical interest. I wasn't able to find an easy way to do this, the closest being searching for pages without the word "outdated", which doesn't work because it's catching any use of "outdated", not just the template.

Machine-readable directory
Since documentation pages are stored in a variety of locations, not just on wiki, we need a method of tracking docs across platforms. I've started gitlab:apaskulin/documentation-directory to experiment with tracking docs with YAML definitions.

Content types on the projects

 * w:English Wikipedia:Featured article criteria
 * w:English Wikipedia:Portal/Guidelines
 * Wikimedia_Blog/Guidelines