Consider deploying docs to a static site

[sau226]

A static site hosting docs would make docs easier to browse for a new developer, as well as structuring content in a clear, consistent format, which is good for search engines and usability. Why present a developer a wall of text on how to set a project up when you can link them to a polished site that tells them what they want to know (e.g. how do I set up?/how do I upgrade this application?/what steps can I take for basic troubleshooting? etc.).

It's comparatively easy to host a static site - all we need to do is enable publishing the site in settings for our main branch, or push our docs to the gh-pages branch and GitHub Pages will host it for free, including the option to use a custom domain. By way of example, an example of a GitHub pages site I have seen in the past would be in the operable/cog-book repo, which aliases in production to a GitHub pages site at https://operable.github.io/cog-book/. Another framework that appears polished and can be deployed for free on a site like Netlify would be GitDocs, which offers built in static search and docs that can live alongside source code, should we go that route. Gitbooks looks something like this.

If we don't mind using something that is not free software (in terms of 'software freedom' and not as in cost), GitBook looks OK and offers open source projects free accounts. GitBook looks something like this.