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 the PR is 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 Tishan 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:

Step	Role	Responsibility
1. Create draft content	Feature developer	Fork the https://github.com/wso2/docs-choreo-dev repository on GitHub and create the draft content following the writing guidelines, markdown file naming conventions, and content formatting guidelines.
2. Validate draft content	Feature developer	Validate that the content includes all necessary steps and artifacts required to test the content.
3. Determine content placement	Feature developer	Determine the appropriate location and structure for the content within the documentation architecture.
4. Submit for review	Feature developer	Submit a pull request (PR) for content review and notify relevant reviewers.
5. Content review and editing	Sub-team member	Collaborate with the feature developer to provide additional information if required.
	Sub-team member	Test and validate the draft content from a peer perspective, including technical accuracy, clarity, and completeness.
	Sub-team member	Copy edit the content, ensuring adherence to writing guidelines, grammar, keyword usage, linking, rephrasing, and SEO best practices.
	Sub-team member	Review the content from the user’s perspective to ensure it addresses why the feature matters, relevant use cases, best practices, and includes diagrams where necessary.
6. Incorporate feedback	Feature developer	Incorporate review feedback and apply suggested changes.
7. Quality assurance check	Feature developer	Perform a final quality assurance check to verify that all feedback has been addressed.
	Sub-team lead	Perform a final quality assurance check and provide final approval for content publishing.
8. Publish content	Feature developer	Merge the PR to publish the content to the documentation dev site. Then, verify the content in the dev site, communicate with Tishan and get the changes pushed to the production doc site

Documentation templates

• Feature documentation template
• Tutorial template