Test Kitchen/Documentation maintenance
This page documents how to maintain the Test Kitchen documentation on Wikitech, including Test Kitchen and subpages..
General principles
- Progressive disclosure
- Test Kitchen 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, Test Kitchen/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 Test Kitchen documentation on Wikitech is organized into these categories:
Workflows
Workflow pages are entry points for users getting started with Test Kitchen using recommended workflows. They describe how to complete a process from start to finish.
- Test Kitchen/Conduct an experiment
- Guide for the experiment workflow using Test Kitchen UI. This page is designed to be linked to from the top of the Test Kitchen UI experiment form. Includes transcluded sections from Create an instrument.
- Test Kitchen/Measure product health
- Guide for the baseline instrument workflow using Test Kitchen UI. This page is designed to be linked to from the top of the Test Kitchen UI baseline instrument form. Includes transcluded sections from Create an instrument.
Guides
Guides provide instructions for completing a task that is part of a workflow.
- Test Kitchen/Create an instrument
- This page is a guide for the manual process for creating an instrument without using Test Kitchen UI. This guide describes a more end-to-end process than other guides due to it being used as the main workflow prior to Test Kitchen UI alpha.
- Test Kitchen/Decommission an instrument
- This page documents the steps to delete an instrument without using Test Kitchen UI.
- Test Kitchen/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.
- SDK docs
- Per-language SDK 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 Test Kitchen/Core properties, Test Kitchen/Interaction data, and language-specific subpages of Test Kitchen/Contextual attributes.
- Test Kitchen/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 Test Kitchen/Contextual attributes/PHP) so that they can also be used on the schema pages.
- Test Kitchen/Custom schemas
- Guide to creating custom schemas
- Test Kitchen/Stream configuration
- Guide to the manual process for configuring an event stream
- Test Kitchen/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 Test Kitchen 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 Test Kitchen and should be kept up to date as the system evolves.
- Test Kitchen/Instrument list
- This page should be redirected to the Experimentation directory in Test Kitchen UI 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 Test Kitchen UI
These pages are linked to from the Test Kitchen UI:[1]
- Test Kitchen
- Test Kitchen/Contextual attributes
- Test Kitchen/Analytics sampling
- Test Kitchen/Schemas (disambiguation page)
Ownership
The Test Kitchen documentation on Wikitech is owned by the Experiment Platform 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)