Guys, it’s no secret that our documentation is outdated and could be improved a lot.
Some have offered to help with that, but I think actually contributing small edits here and there is too hard and therefore does not happen.
I have tried a wiki before (mediawiki), but didn’t like the formatting/syntax and not many people contributed.
Our current documentation is on readthedocs (via docs.brewpi.com) and version controlled on GitHub.
It’s based on Sphinx with plugins to support markdown.
While GitHub is great to version the docs and manage contributions, I think the barrier is a bit high. You have to clone the docs repo, get the Sphinx build going, do your small change and then create a pull request. With a barrier that high, small contributions just don’t happen.
So to summarize: does anyone has a good suggestion for an easy to use system to manage user documentation?
For documenting our code, using Sphinx (combined with other tools like Doxygen) is probably fine, as the code is already on GitHub. For the user docs, I’d like something more like a wiki. But a modern, WYSIWYG, easy to manage, and as nice to use as this discourse forum.
Based on searching, this is an old thread but thought it might be a good idea to bring to the surface with the development of Brewblox. There are a lot of users of the software and the equipment on here and instead of trying to piece together bits and pieces from threads all over the place, it seemed like a good idea to bring this up again.
I know that we use Github https://github.com/brewblox/brewblox-documentation (still a Noob at that), there is the feature list here: https://waffle.io/BrewBlox/waffle & your basic setup information is here: https://brewblox.netlify.com/
But as it was mentioned before is there a better or new and improved way of improving the community knowledge base from the user stand point so we don’t take away as much time from @Elco, @Bob_Steers and Team?
Side note: the Github repository (brewblox/brewblox-documentation) is the source code for the https://brewblox.netlify.com/ page. If you want to suggest changes to pages in netlify, you can click the Edit this page link at the bottom.
Other than that, what would you say is lacking?
Overview of resources (github / dashboard / documentation links)
Overview of solved user issues
User-written descriptions of their setup / solutions