Metrics Platform/Documentation maintenance
This page documents how to maintain the Metrics Platform documentation on Wikitech, including Metrics Platform and subpages..
General principles
- Progressive disclosure
- Metrics Platform is a complex product. To avoid overwhelming users, avoid giving users all information all at once. Instead, divide the process into steps, and provide only the information users need to complete each step.
- Reference the code
- Where possible, add citations to the docs that reference code files where functionality is defined. For example, Metrics Platform/Contextual attributes#References.
- Use examples
- Examples are the most helpful tool for users. Use them as much as possible.
- Prioritize core workflows
- We want users to use the base schemas, so we should prioritize base-schema workflows in the docs. Try to move complexity related to using custom schemas out of main workflow docs and onto specialized pages, so that the experience of base-schema users is as clear and simple as possible.
- Avoid duplication
- Duplicated docs are more likely to become out of date. Use transclusion and linking to limit duplication of content to the absolute minimum.
Structure
The Metrics Platform documentation on Wikitech is organized into these categories:
Workflows
Workflow pages are entry points for users getting started with Metrics Platform using recommended workflows. They describe how to complete a process from start to finish.
- Metrics Platform/Conduct an experiment
- Guide for the experiment workflow using MPIC. This page is designed to be linked to from the top of the MPIC experiment form. Includes transcluded sections from Create an instrument.
- Metrics Platform/Measure product health
- Guide for the baseline instrument workflow using MPIC. This page is designed to be linked to from the top of the MPIC baseline instrument form. Includes transcluded sections from Create an instrument.
Guides
Guides provide instructions for completing a task that is part of a workflow.
- Metrics Platform/Create an instrument
- This page is a guide for the manual process for creating an instrument without using MPIC. This guide describes a more end-to-end process than other guides due to it being used as the main workflow prior to the MPIC alpha.
- Metrics Platform/Decommission an instrument
- This page documents the steps to delete an instrument without using MPIC.
- Metrics Platform/Local development setup
- This page is a setup guide for instrument developers writing instrument code. It should be as simple as possible and focus on instruments using the base schemas.
System docs
System docs describe the behavior of the system as currently implemented. They include API docs, schema docs, and other reference docs. These docs are meant to be used by both users and maintainers, but they should include only information relevant to both groups.
- API docs
- Per-language API docs
- Web schema and app schema docs
- These pages document the base schemas by listing schema properties by category. They're designed to help users understand what properties are supported by the base schemas when designing their instruments. These pages intentionally do not include property descriptions or types to avoid duplicating information stored in the schema definitions. These pages include transcluded content from Metrics Platform/Core properties, Metrics Platform/Interaction data, and language-specific subpages of Metrics Platform/Contextual attributes.
- Metrics Platform/Contextual attributes
- This page lists the contextual attributes supported by each client. Like the schema pages, this page intentionally does not include property descriptions or types to avoid duplicating information stored in the schema definitions. The lists of properties on this page are transcluded from language specific subpages (such as Metrics Platform/Contextual attributes/PHP) so that they can also be used on the schema pages.
- Metrics Platform/Custom schemas
- Guide to creating custom schemas
- Metrics Platform/Stream configuration
- Guide to the manual process for configuring an event stream
- Metrics Platform/Analytics sampling
- Supplement to the stream configuration guide documenting sampling parameters
Maintainer docs
Maintainer docs include any content that is only relevant to maintainers of the Metrics Platform system. These should be the most complex docs and capture everything maintainers need to know about working with the system.
Meta docs
The Glossary and FAQ pages, as well as the About content on the landing page, are key resources for users deciding whether to use Metrics Platform and should be kept up to date as the system evolves.
- Metrics Platform/Instrument list
- This page should be redirected to the MPIC Experimentation directory once it becomes the canonical source for active instruments.
Section transclusion
Some pages use section transclusion to reuse specific parts of a page within another page. Here's an example of the syntax to enable section transclusion:
In the source page:
<section begin="section-name" />
This is the section text.<section end="section-name" />
In the destination page:
{{#lst:Source-page title|section-name}}
Documentation pages linked to from MPIC
These pages are linked to from the MPIC user interface:[1]
- Metrics Platform
- Metrics Platform/Contextual attributes
- Metrics Platform/Analytics sampling
- Metrics Platform/Schemas (disambiguation page)
Ownership
The Metrics Platform documentation on Wikitech is owned by the Data Products team. The templates in Google Drive are owned by Product Analytics.
See also
- Information architecture design, October 2024
- Documentation tour, October 31, 2024 (meeting recording, restricted access)