How to Build Outstanding Documentation With Docusaurus 🦖

Documentation is the primary touchpoint of any software. No matter how great a project is, bad documentation can easily lead to the project being disregarded.

Why Documentation?

It might seem obvious, but why do we need documentation? If our codebase is pretty well commented, doesn’t that make separate documentation obsolete? No. And I’ll tell you why.

1. Developers might want to check documentation before deciding what project to use in their software.
2. It can be cumbersome to go through dozens of files to see what a function does
3. Separate documentation provides additional benefits, such as quick links, interactive playgrounds, indexing, etc.
4. Sometimes our software is more than just the code. Think “Getting Started” or build instructions etc.
5. The code is restricted and not publicly available

At the very least, most open-source projects have some markdown files in their repos. There are quite a few downsides to that:

1. Changing documentation requires a PR or commit. (This can be a good thing, though).
2. Users need access to the repo.
3. Markdown is not that full-featured and lacks some features.
4. You have to navigate between multiple files.

Enter Docusaurus 🦖📜