Product documentation

The documentation service publishes practical guides for your application's users. Open Documentation to prepare its scope and follow writing progress.

Before you start — Identify the users and tasks the guides must explain. Prepare real prerequisites, interface labels and outcomes. A planned capability must be distinguished from an action users can already perform.

Review the sections to write

Compare proposed coverage with the actual application before beginning the guide writing.

1. Open Documentation and its configuration.
2. Review Getting started, Module guides and FAQ.
3. Inspect the definitions and states for the sections relevant to your application.
4. Compare the planned guides with the tasks users can actually perform.

An optional API reference belongs to a project whose API exists and is active. Do not treat a planned endpoint as a working integration guide.

Supply the missing information

Supply the rule and result requested by the question, beyond a general screen description.

1. Find the section requesting clarification.
2. Click Answer.
3. Describe the user task, its prerequisites and the result to explain.
4. Click Submit my answers and follow the section state; your answers re-run the section's analysis.

Use examples and the actual application labels. A guide should tell a user what to do, rather than only describing the screen.

Launch the guide writing

Start writing from the ready overview and follow the recorded request and questions.

1. Return to the documentation overview.
2. Check that all your modules are shipped; until they are, the launch action stays unavailable.
3. Click Launch the documentation writing when the action is available.
4. Follow Writing progress and any questions.

The request starts the writing workflow. Wait for its state to progress rather than launching duplicates.

Review the public guides

Follow the instructions as a user, including the final outcome and related next task.

1. Open the documentation service address.
2. Choose a topic from its navigation.
3. Follow the procedure in the actual application.
4. Check the topic in every published language.
5. Open its related articles and verify that they lead to useful next tasks.

The guide matches the application, its language and the useful follow-up destinations.

Tip — Review a guide after an application change that affects its task, label or result. Translation should preserve the full procedure rather than becoming a shorter summary.

An account guide should explain who can act, the environment, required fields, confirmation and resulting account state. “The page contains a form” does not explain how to finish the task or recognize a validation error.