thewca
Agree a basic framework for documentation
Overview
With documentation on the horizon (yay!), we would benefit from establishing some key points to how documentation is written.
These include:
- Where will documentation be hosted
- What format will documentation be written in
- What is the overall structure/sitemap of documentation?
- (optional) What is the documentation roadmap - ie, how do we want to prioritise achieving that sitemap?
Where will documentation be hosted
I think there are 2 main options - hosting documentation in the Wiki in this repo, or creating a documentation website.
Documentation website (with static-site generator)
Creating a documentation website with Github Pages is relatively straightforward - it could be done either in this repo's equivalent of main, or on a separate gh-pages branch (which may be preferable, as we can then update documentation without being dependent on the status of main - I'm not sure where branch management is at/what the vision for it is).
Especially given that the project is Ruby-based, we could use Jekyll, which integrates natively with Github Pages.
I set up an MVP documentation website for cubing.js using Jekyll, for example: https://dunkonit.github.io/cubing.js/api-reference/
The whole thing is basically just markdown files, very easy to maintain.
What format will documentation be written in
Personally, I strongly favour Markdown - it is very easy to write, and incredibly portable. This would mean that the documentation is platform/solution-independent.
What is the overall structure/sitemap of documentation?
While not strictly essential, I would strongly advocate for setting something like this up - at least personally, I think that working within a general structure/framework makes things easier, and having a basic structure laid out makes it easy for new contributors to step in.
