Documentation Process

This page describes the Choreo documentation process.

Why document

To help end users understand and use Choreo effectively to get their use cases done

What to document

Any aspect that is not intuitive to be done only via the UI or information on using product configurations need to be documented. For example, features involving many steps, learning material, complex configurations, etc.

How to document?

You must follow the Choreo documentation guidelines and create content in Markdown.

Documentation process

1. Fork the https://github.com/wso2/docs-choreo-dev repository on GitHub.
2. Add/edit necessary Markdown files as well as relevant image files.

   Note: You must follow the writing guidelines, markdown file naming conventions, and content formatting guidelines when you create content.

3. If you add a new Markdown content file, add the file appropriately as an entry in the mkdocs.yml file.
4. Send a pull request (PR).
5. Once you add all necessary content and you are ready for a review, remove any Draft markers and assign a reviewer.
6. Once the review is done and the PR is merged, verify the overall content in the documentation dev site.
7. Once verified in the dev site, communicate with the doc team and get the changes pushed to the production doc site.

Roles and responsibilities

Here’s a summary of the main roles involved in the documentation process and their responsibilities:

Role	Responsibility
PR owner/product SME	Creating the draft content according to the documentation process and guidelines.
	Validating the content.
	Making sure all the required steps and artifacts needed to test the content is available.
	Working with the writer to provide additional information if required.
Writer	Testing and validating the draft content.
	Copy editing the content, i.e., grammar checks, keyword usage, linking, rephrasing, SEO, etc.
	Reviewing the content from the user’s perspective to ensure it answers the question “why?”, addresses use cases, and includes best practices and diagrams.
	Determining the best location and structure for the content in the documentation architecture.
	Publishing and maintaining the content.

Documentation templates

• Feature documentation template
• Tutorial template