Documentation Process

This document describes the process to follow when you want to contribute to documentation on a new feature or improvement in Choreo,

1. Create a document in Markdown format with a description of the feature, how it works, the problems it solves, etc. Be sure to include all the required details to use as the foundation for the documentation.
2. Send a pull request to https://github.com/wso2/docs-choreo-dev/tree/dev/en.

If you want to share a google doc with details, you must create a new task type issue in https://github.com/wso2-enterprise/choreo/issues, add the Type/Docs, Area/DocSite labels, and attach a Google document with all the required details related to the task.

Following is a feature document template that describes what each section should include:

[Introduction]

The introduction is a brief description of your feature. Write a paragraph or two that summarizes the purpose and function of this feature. Start with a one- or two-sentence summary of what the feature does and/or what problem it solves. You can give more descriptive information in a second paragraph. This paragraph should answer the questions: "What does this feature do?" and "Why would I use it?" If your feature has a range of functionality, you can briefly mention them here and go into detail later in the subsequent sections.

[Prerequisites]

If the new feature requires any prerequisites to get started (another feature, etc.), mention it here. Also, mention any warnings or other important notices if applicable.

[Usage]

Explain the user stories/scenarios that the feature applies to and information on how to use the feature.

[Examples]

Show what the feature does as concisely as possible. Users should be able to figure out how the feature solves their problem by looking at the example. Make sure the functionality you are providing is obvious, and that any related APIs, configurations, data types, and other elements are included or mentioned.

[Limitations]

Describe infrastructure compatibility, version compatibility, etc. If there are known issues, include them under specific headings here.

[Best practices]

Highlight the best practices about the feature and its usage.

[Troubleshooting & FAQs]

Address questions that are likely to be asked frequently by users. Outline common problems that users would encounter along with solutions. Explain how the users may get to the root of the problem through troubleshooting. A list of error codes resulting from the feature, problem logs with causes, and an exception table if applicable.