Finding the right documentation software
We had a few criteria for the right documentation software. Those being:
- Community members can contribute without hassles.
- Data can be accessed using open formats.
While we initially considered going with Sphinx, the experience isn’t quite where we want it. Installing it isn’t straight forward, and reStructuredText isn’t intuitive to many people.
We ultimately settled on GitBook. Despite it not being an open-source solution, it offers us the following advantages:
- Regular contributors can edit the documentation using the GitBook web UI.
- Non-regular contributors can edit the documentation by making a Pull Request on GitHub.
- GitBook provides hosting for us. And since we are an open-source project, this even for free.
As GitBook stores the data using Markdown in GitHub, there is also not much vendor lock-in. Any potential migration to other services in the future should thus be easily possible.
We’d be happy for any contributions to our documentation. Just submit a Pull Request or Issue to our GitHub repositories, and we’d happily incorporate your changes.