Documentation/Documentation types

Documentation types are useful concepts for organizing and maintaining documentation. This page describes the types of documentation found in Wikimedia technical docs.

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

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

List of documentation types
This is an uncurated list of documentation 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
 * decision record
 * Documentation/Decision records

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

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