Documentation Guidelines

As part of the Definition of Done, documentation is a necessary part of any Sprint deliverable. Use these guidelines for any documentation you create in a Sprint.

General guidelines

1. Documentation can be in the form of a series of notes for the tech writer to work from.

2. Documentation you provide does not have to be in a perfect state, but it should provide enough details for the tech writer to write a final draft.

3. Documentation must be in Markdown format.

4. Documentation files should be created in the following directories:

   • pwa-devdocs/src/_drafts (preferred)
   • packages/peregrine/docs
   • packages/peregrine/src/**/_docs_/
   • packages/pwa-buildpack/docs

5. Break up sentences into separate lines to make the raw markdown easier to read and review.

   Example:

   The quick brown fox jumps over the lazy dog.
   Grumpy wizards make toxic brew for the evil queen and jack.

6. Use reference-style links to make the raw markdown easier to read and review. Link definitions must be located at the bottom of the page.

   Example:

   Visit [Daring Fireball][] for more information.
   
   [Daring Fireball]: http://daringfireball.net/

UI component documentation

Every UI component work in the Peregrine library should have the following:

• A Storybook story for the new component.

  Example: Price story

• Reference documentation that provides the following information:

  • A summary of the UI component and what it can be used for
  • A list of props with descriptions for each prop
  • One or more code examples

  Example: Item reference documentation

Feature documentation

Feature documentation is required for any new PWA Studio feature that third party developers can use or configure in their own projects.

The documentation must have the following content:

• A description of the feature (What is it?)
• Use cases for the feature (Why should I use it?)
• A simple example of the feature (How do I use it?)
• Descriptions of the API and its configuration points

Example: REST API client

Venia implementation documentation

Since Venia is a reference storefront, we must document how it was put together so that others can learn how to create their own storefront.

Venia implementation documentation should include the following:

• A description of what was implemented and what problem or use case it addresses
• A description of the general approach for the implementation
• A list of PWA Studio components/features that were used and how
• A list of Magento endpoints used in the implementation

Example: REST checkout flow