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.

Prior art

Key doc review process

2021-2022

From Documentation/Review_template#Content_types:

• Landing page: Landing pages are link hubs that help the reader find information. Landing pages are navigation oriented.
  • Cross-collection landing page
    I found the distinction between landing pages and cross-collection landing pages to be too complicated, so I stopped using the later.
• 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

"Patterns" was too obscure of a name for this.

• The lists of examples with links is helpful. What information can we include to help users decide which examples will be helpful to them?
• The lists of elements in the "Description" section are too long and hard to parse. I can see using this for an automated linter that checked for the presence of these elements, but not for human use.
• The lists of templates and availability are difficult to create and maintain, but very useful. They remind me of browser compatibility charts. Can we automate this? Should we create tasks for importing some of these to missing wikis?

Documentation/Toolkit

2022

Documentation/Toolkit#Use_templates_to_create_documentation

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

Are API docs and library docs documentation types? I think of API docs as a general term for all the documentation required for an API, including an introduction, reference, tutorial, and explanation. See Documentation/API_documentation#Types_of_API_documentation.

See also

• w:English Wikipedia:Featured article criteria
• w:English Wikipedia:Portal/Guidelines
• meta:Wikimedia_Blog/Guidelines#Outlines_for_topics

References

• Diátaxis documentation framework