How to contribute to WSO2 API Manager Documentation?

Want to become a contributor for WSO2 API Manager docs? Then this article is for you.

Photo by Aaron Burden on Unsplash

I will keep this article as simple as possible so that you can dive in right away. Short and Sweet! 🙂

• Link to the documentation → https://apim.docs.wso2.com/en/latest/
• GitHub repository for docs → https://github.com/wso2/docs-apim
• Active branch for next release documentation → master
• Branches for previous releases → Named after the release version. For example, branch 4.2.0 is for the documentation of WSO2 API Manager version 4.2.0.
• Technology used for writing → MkDocs

How to get started?

• Fork the docs-apim repo.
• Clone the fork of docs-apim repo to your local machine.
• Set remote upstream of the Git repository to https://github.com/wso2/docs-apim.git. You can use the command below.

git remote add upstream https://github.com/wso2/docs-apim.git

• Install Python
• Install pip
• Install the required pip packages using the following commands. If you are using Python 2, use pip command and if you are using Python 3, use pip3 command.

pip install mkdocs
pip install mkdocs-material
pip install markdown-include
pip install pymdown-extensions

This will install MkDocs for you.

Now you are done with the setup required to start with writing documentation. 👍

To see if MkDocs is correctly installed, run the following command in the terminal. It will print the version of MkDocs if it is correct.

mkdocs —-version

Start the local MkDocs Server

• Now move into the docs-apim/en/ folder in the cloned repository. Remember to checkout to the correct branch based on the documentation that you need to edit.

cd docs-apim/en/

• Run the following command to start the server.

mkdocs serve

When you see the following log, in the terminal that you executed the command above, you can access the server using the given url (http://localhost:8000) from the browser. This is the docs server running locally in your machine.

[I 210110 08:11:35 server:335] Serving on http://localhost:8000
[I 210110 08:11:35 handlers:62] Start watching changes

Now you can edit the document and view your changes locally by running mkdocs serve. Make sure to reload the browser to view your changes. After making a change, you have to save it and wait for the above log to reappear.

View edited docs on the fly

If you want to view the edited docs on the fly without having to manually reload the browser, follow the steps below.

• Open docs-apim/en/mkdocs.yml file.
• Change the following configuration to false as fallows.

#Breaks build if there’s a warning
strict: false

• Now run the following command which will allow you to make the server load only the changed items and display the changes faster without having to manually reload the browser.

mkdocs serve --dirtyreload

Make sure to change the above configuration to true again when committing your changes. In a particular branch, if it is false by default, leave it as it is.

Where to make the changes?

Here I will explain to you the basic but most important things you should know when making changes to the documentation.

• It is in the docs-apim/en/mkdocs.yml file, that we define the paths to the relevant .md file that contains content for a specific topic. You can find that under the nav section as shown below.

mkdocs.yml

• Find the relevant .md file from the mkdocs.yml file and make changes accordingly. Under the nav section, on the left of the key value pairs is what you see as headings in the documentation when accessing through the browser. This will help you to find the respective document easily.
• If you are planing to include screenshots in the page that you are writing, add all the images in to the following location.

docs-apim/en/docs/assets/img/<relevant-folder>

• Name the images in simple letters and separate the words with a hyphen. For example, create-new-api.png. The relevant-folder can be decided based on the location of the documentation. For example if you are adding an image to create-a-rest-api.md file, add it under its super parent section which is “learn” according to the structure in mkdocs.yaml file.
• When adding screenshots or images to the documentation, to view them locally, change the image file path as follows. Remove {{base_path}} from the url and add the relative path to the assets folder where the image resides.


But when committing the changes to the repository, make sure to change it to {{base_path}} again. For your information, this base_path is defined in mkdocs.yml file.

Best practises to follow

Make sure you follow the practises defined in this wiki when making changes to the docs-apim repository.

You can now start contributing to WSO2 API Manager documentation and play your part to increase your visibility and competency.

Note : Please refer this link to see what issues need to be addressed. If you are making any changes to an already released version of WSO2 API Manager, make sure to send in a PR to the master branch as well, if the change is applicable.

If you find any outdated content or issues with this article, please feel free to create an issue at Developer Corner Git repository here. Let’s grow together and help others in their journey too!

If you like this article please give it a clap. 🙂

Cheers! Happy Contributing!