Documentation Guidelines

Documentation guidelines

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

General guidelines

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

2. Docs 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 updates that affect the current release can be made directly to the file.

5. If a doc update on a file only affects the next release, copy the directory containing the index.md file into the pwa-devdocs/_drafts directory and make the changes to that draft version.

6. Documentation that is not ready to be published must be created in the pwa-devdocs/_drafts directory.

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

8. 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/

Component documentation

All public API in Peregrine and Venia components require documentation in the source code.

Source code documentation must follow JSDoc format so it can be converted into a markdown topic.

Component documentation must include the following:

• A description of the function/object
• A list of any parameters or properties it expects and a description for each
• A description of the return type (if any)

Example: ToastContainer documentation in source code

Generating the markdown

Follow these steps to generate the markdown files from JSDocs in files:

1. Navigate to the pwa-devdocs directory

2. Install the node dependencies: npm install

3. Add the component file path to one of the following files:

   • pwa-devdocs/scripts/create-reference-docs/config/peregrine/index.js
   • pwa-devdocs/scripts/create-reference-docs/config/venia-concept/index.js

4. Build the reference docs: npm run build:reference-doc-snippets

5. Auto-generated files will be located in the pwa-devdocs/src/_include/auto-generated directory

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