Creating WSO2 Updates 2.0 Documentation
WSO2 Updates is the newest tool introduced by WSO2 to Update product packs. The customer will receive fixes for possible security weaknesses and software enhancements and much more by using WSO2 Updates 2.0. This model surpasses the WUM and In-Place tool that was used by customers to update their product packages. Read more about WSO2 updates 2.0 and its composition that would enhance the update experience by perusing https://updates.docs.wso2.com/en/latest
Today I am penning this blog to disseminate information about the document creation process, its implementation, and post documentation processes one has to be heedful of.
First, make sure the documents are tested on your local environment for any mkdocs syntax defects. Always refer to the material available on the internet to get the most when making markdown documents. Later it is very important to carry out a thorough review of the content and test the content from a user's perspective. The information has to be complete, informative, clear, and readable. It should capture the willing audience with interest to follow on. The WSO2 Updates 2.0 has accomplished the above requirements by its document flow, a simple set of instructions to update that doesn't flood the user with too much complex information, and a complete guide for users with the addition of Frequently asked questions(FAQ) and Best Practises guide. After the documents are ready with reviews by peers and tested, this is the stage you commit your work to a new git repository. The WSO2 norm is to place the documents in wso2/docs-updates/tree/master/en/docs/updates directory.
Next, it is better to make a separate git branch to commit your everyday changes and later merge to the master branch. Inform the Digital Operations team about your intentions to host the links to a pre-established link.
Then self check where you want the new set of documents to appear. Discuss with the team where new changes should be implied, and what are the best ways to improve promotion to the new documentation. As for the Updates documents, I have amended messages displayed when users are taking OS-specific updates, changed individual installer options pages, revise the existing documentation site to show both previous and current updates documents. It is also important to access what is shown in a google search when you search for ‘WSO2 updates’ these details should be considered and dealt with when publishing the new document.
Further make sure that you have incorporated a new and improved search mechanisam like Algolia to your documentation site so that site visitors find it easy to search keywords and get to content.
Finally, take another closer look and leverage quality to the documents by revisiting and continuous improvements. Make sure the documents are easy to access and the content is clear in its purpose. Like to end this blog with a quote from a practical and useful book[ if time permits I recommend you to read it]:
Make tiny, easy changes that deliver big results —
Atomic Habits, James Clear
Learn more about:
— Mkdocs : https://www.markdownguide.org/tools/mkdocs/
— Refer Mkdocs syntax sheet: https://www.markdownguide.org/basic-syntax/