Structure of a document
When you contribute a new feature to WSO2 products, you must include a feature document that fully describes the feature how it’s used the problems it solves, etc.
The feature document should contain high-quality content that can be used as the foundation for product documentation, marketing content, and training materials with minimal editing.
The document should be in Markdown format and accompany your pull request. Following is a template for this feature document and what each section should include.
A template (document-template.md) can be found in the github repository.
The introduction is your 30-second elevator pitch for your feature.
* Paragraph 1 - Start with a one- or two-sentence summary and describe what the problem is/ what problem this feature solves.
* Paragraph 2 - Describe what this feature does and why would someone use it. Use a diagram if possible to explain better.
Specify the required environment (e.g. tested JDK, OS, and DB versions) If your feature requires anything extra before setting up, mention it here.
-
Example:
- Step 1 - Create a prototype API with mock response payloads
-
Walk through the feature using this section or with multiple steps.
-
Mention the configurations that need to be done.
-
Add code samples when necessary
-
Use screenshots whenever the UI is not intuitive or the step is complex.
-
Carefully add notes whenever needed.
- Avoid using the word please. For e.g. Please click on save
- Use bold text for the action. For e.g. Click Save.
List down other topics a reader would be interested in.