Documentation, moi? Nov 1, 2017

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:

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:

This new docs site is static and based on:

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 new issue tracker. Yes, it’s very clear that the situation is bad, it’s now a matter of making improvements.

Weblog © Jean-Claude Wippler. Generated by Hugo.