Technical Reports

TECHNICAL REPORTS

WSO2 Documentation Guidelines

By WSO2 Technical Content and Certification Team
November 2017 | TR-002

1. Introduction

The purpose of this document is to give users some guidelines for producing different types of content for when contributing features, bug fixes, APIs, etc. to WSO2 products.

For information on contributing to WSO2 products, see Contributing to the Code Base.

2. Features

This section explains what to include in a document that describes a new feature of a product.

2.1 Business requirement

Explain, preferably with the help of a high-level diagram, the business requirement and the use case.

Example: The API Console is introduced to the API Store as most users like to see API invocation facility provided in the product’s UI itself. It enables them to test their APIs without having to use a separate tool like Curl.

Explain how this use case fits into a larger scenario wherever relevant.

Example: Enabling SAML SSO carbon authenticator through a corresponding configuration file plays a key role when configuring multi-factor authentication for the WSO2 Identity Server’s Management Console.

2.2 Key concepts

Explain any key concepts or industry standards that the user needs to have prior knowledge about in order to understand the new product feature.

2.3 Test steps and artifacts

Test the use case in the developer’s environment and write down all the steps necessary to configure and test it.

Describe all the important configuration details along with the files, file paths, etc. If helpful, add screenshots of the configs. Attach all the artifacts required for testing such as samples, configuration files, and APIs. Avoid under-the-hood implementation details and mention only what the user needs to configure this feature.

2.4 Affected docs

  • What areas of the existing docs are affected by this feature?
    • Example: Use the new API Console in tutorials and samples instead of Curl.
  • Is this feature related to upgrade or migration? If so, how?
  • Is this feature related to deployment? If so, how?

3. Bug fixes and improvements

This section explains what to include in a document that explains a bug-fix or an improvement.

3.1 Business requirement

Explain, preferably with the help of a high-level diagram, the business requirement and the use case.

3.2 Test steps and artifacts

Include all the information necessary to fix the bug/improvement. Link to relevant blogs and articles. If you have already tested this or done some research, give all the information that you know so that we save the time and effort spent on rework.

Describe all the important configuration details along with the files, file paths, etc. If helpful, add screenshots of the configs. Attach all the artifacts required for testing such as samples, configuration files, and APIs. Avoid under-the-hood implementation details and mention only what the user needs to configure this fix/improvement.

3.3 Affected docs

  • What areas of the doc are affected by this bug fix/improvement?
  • Is this related to upgrade or migration? If so, how?
  • Is this related to deployment? If so, how?

3.4 Related issues

List the JIRA or Github issues related to this fix/improvement.

4. Product upgrade guide

Given below is the WSO2 product upgrade guide’s template.

4.1 Upgrading from the previous release

Copy the following text over to your page and change the placeholders.

The followings steps describe how to upgrade from <Previous product version> to <Current product version>. To upgrade from a version older than <Previous product version>, start from the documentation that was released immediately after your current release and upgrade incrementally.

If you want to move your current product configurations to a different environment (e.g., from Test to Production) within the same product version, see the Migration Guide. <insert the link to the migration guide>

4.2 Preparing to upgrade

  • Limitations and incompatibilities, if any.
  • How to back up the databases.
  • Expected system downtime.
  • Any recommendations before you begin (e.g., what third-party software is recommended to be upgraded along with this, recommended time of migration such as low traffic periods in the system, etc.)

4.3 Upgrading the database/registry

Give step-by-step instructions on what databases to change and what changes to do in each database.

4.4 Upgrading the configurations

Describe the config files and applications that can simply be moved from the older version to the new version without being changed.

  • How to move the applications, tenants, workflows, user stores etc. (You can have separate subsections for each type. These subsections may vary depending on the product.)
  • How to move the configuration files. (Can the users simply override the existing files, or do we have to warn them of any configurations that might be overridden if they copy/paste?)

4.5 Testing the upgrade

Mention what tests the user should run to make sure that the upgrade has not caused any issues in the system.

5. Product migration guide

Include the following sections in a WSO2 product’s migration guide.

  • Give a brief introduction as to what migration is.
  • Add a link to the upgrade page in case the user wants to upgrade to a new release.
  • Explain how to create a CApp with the current server’s configs and then deploy that CApp in the new environment.

6. REST API documentation

Cover the following section in REST API documentation:

  • Introduction to the API. Should explain what the API does.
  • Parameters of the API. Should cover each parameter’s name, description, datatype, and default and fixed values (if any).
  • Request format.
  • Response format.
  • Sample request. For example, the Curl command.

7. Sample documentation

Follow this template when adding samples to any WSO2 product.

7.1 Title

Use a meaningful name for the title of the sample so that the business use case addressed in the sample is clear. The title should also contain possible search terms.

Example:
Poor title: Excel Sample
Good title: Service Enabling the Data in an Excel Sheet

7.2 Introduction

Explain the following as applicable:

  • The objective of the sample and the use case it demonstrates.
  • The technical concepts, or if the concept is already explained in the documentation, link to the relevant pages. Otherwise, provide an appropriate external reference. For example, when a sample demonstrates the usage of MTOM capability, explain or provide reference to what MTOM is.
  • Assumptions you are making. One possible assumption is that the user knows certain industry standards and well-known technical concepts. We can state them here so that users are aware of what they are expected to know to follow the sample.

7.3 Prerequisites

  • Additional software and databases required to run the sample, and how to download, install, and configure them. If already explained, link to the current doc or external sources.
  • Any packages or files (such as .jar files) to be installed and URLs to change.
  • Any existing config files that need to be changed and how.

Wherever possible and appropriate, explain why the user needs each prerequisite. We want the users to understand the context of what they are doing along the way.

7.4 Building the sample

Sample file location and how to build the sample. (E.g., using Ant).

7.5 Executing the sample

Step-by-step instructions to execute the sample and view results. This section may include:

  • Sub-titles and diagrams as appropriate.
  • Configuration files and code blocks.
  • Management Console screenshots.
  • How to run any sample clients.
  • How to view results and screenshots of results.

Wherever possible and appropriate, explain why they are taking the current step and what the results indicate. We want users to understand the context.

7.6 Conclusion/analysis of results

Analyze the results and derive conclusions.

For more details about our solutions or to discuss a specific requirement contact us.

x

Interested in similar content?