Skip to main content

Documentation Tooling Project (Docusaurus Site)

This project involved auditing and restructuring documentation for Microcks using Docusaurus.

🔗 Live Site​

What I Improved​

The main improvements made to this documentation were in punctuation, sentence structure, and typos.

  • For example, on the Getting Started page, the word ephemeral was misspelled. Also, on the same page, the phrase:

    "open a new browser tab and point to the http://localhost:8585"

    should be:

    "Open a new browser tab and navigate to http://localhost:8585"

since we are referring to a URL.

  • Additionally, in the Loading a Sample section on the Getting Started page, there were word repetitions, such as:

    "We provide different samples that illustrate the different capabilities"

    Instead, using synonyms avoids repetition:

    "We provide various samples that illustrate the capabilities."

Challenges​

I did not encounter any major challenges while working on this project. The initial challenge was selecting an open-source project to work with.

Another challenge is that, as I am relatively new to technical writing, I may have overlooked issues that someone with more experience in documentation might have noticed. Any guidance or tips on how to improve and move forward would be greatly appreciated.

What I Learnt​

I learned alot during this exercise:

  • I enhanced my knowledge of configuring the sidebar. I was able to add a third-level hierarchy to the sidebar, to improve navigation and make it easy to find nested content.
  • On the using-microcks-cli page, I embedded links to the connecting-to-microcks-api and getting-started pages, which helped me understand cross-referencing between documentation pages for a smoother user experience.
  • I learned how to incorporate HTML elements within Markdown for more flexible formatting.
  • I tried using MarkdownLint in VS code for formatting my files for a consistent, clean and readable documentation.