For years, my weakest spot has always been documentation, and it’s been sticking out like a sore thumb. For all the code I’ve been slinging into this world, paid and unpaid, open and closed, documentation has been:
Incomplete! Inaccurate! Disorganised! Out-dated! Confusing! Terse! Unfocused!
Being a “starter” and not a “finisher”, and knowing that work on documentation tends to come last, it has become a … mess:
- an ageing wiki on Redmine
- and another one for hardware
- a bunch of docs made with Doxygen
- outdated HouseMon&Tosqa stuff
- a (newer) area for embello andflib
The same holds for bug/issue trackers, but luckily that situation has now been more or less consolidated into just a few on GitHub.
I’ve always been fond of Andy Tanenbaum’s quote in his “Computer Networks” book:
The nice thing about standards is that you have so many to choose from.
In combination with this insight from xkcd:
Let me add my own variant: there are too many doc areas, so let’s create a new one!
Seriously. I’ve recently set up a new site at https://docs.jeelabs.org with these goals:
- act as home pages for projects, at a finer granularity than GitHub repo’s
- it has to be snappy and searchable
- clear navigation, even on mobile
- allow others to update information (edits auto-generate new content)
- no discussion, just facts (discussions belong in a separate issue tracker)
- stable URLs: once added, pages stay
This new docs site is static and based on:
- Hugo, which I also use for the weblog
- GitHub, where all source code lives
- Learn theme for layout & navigation
When you go to docs.jeelabs.org, you’ll see:
The sidebar folds open to reveal nested menu’s and slides away on narrow screens. The search box works across the entire site using some clever JavaScript magic, and right/left arrows move from page to page.
Every page has an Edit this page link which takes you to GitHub’s text editor if you have commit access, or lets you create a fork to submit a pull request otherwise.
For discussion, tips, or even criticism about these docs, there’s now an issue tracker.
Getting this site into shape and complete enough to add value is going to be a heck of a job. So my first goal is a bit humbler: let’s just try and get pointers to all the existing documentation into this new site. With a bit of effort, it should be possible to at least get rid of the most confusing info out there, and make the pages on this new site the best starting point for everything Jee’ish…
I welcome all your help (and discussion / complaints, if it will lead to a better site) - on the forum or the newissue tracker. Yes, it’s very clear that the situation is bad, it’s now a matter of making improvements.