Use Just the Docs Jekyll theme and host on GitHub Pages

Context and Problem Statement

Documentation must be stored close to the code to be kept updated but must also be easily accessible if it is to be read. Decisions and other documentation should also be easily searchable both for a developer and an end-user. Where should the documentation be stored and should it be hosted?

Considered Options

Docs in a separate repo, not hosted
Docs in a separate repo, hosted
Docs in the same repo, not hosted
Docs in the same repo, hosted

Decision Outcome

Chosen option: “Docs in the same repo, hosted”, because we get the best of both worlds. The documentation is at the fingertips of the developer and the end-user.

Pros and Cons of the Options

Docs in a separate repo, not hosted

Good, because it is easy to set up
Bad, because docs are “out of sight, out of mind”
Bad, because docs are hard to access for users

Docs in a separate repo, hosted

Good, because docs can be accessed by users
Bad, because docs are “out of sight, out of mind”

Docs in the same repo, not hosted

Good, because docs are close to the source code
Bad, because docs are hard to access for users

Docs in the same repo, hosted

Good, because docs are close to the source code
Good, because docs can be accessed by users
Bad, because deployment is more complicated

More Information

GitHub pages are quick and easy to configure, and Just the Docs Jekyll theme provides search and a dark theme.