As you may have seen in a number of discussions on the forum (such as this one), things are still in flux w.r.t. documentation of software / libraries / hardware coming out of JeeLabs.

I’ve been agonizing for ages about this. It’s a recurring theme and it drives me up the wall about once a year.

Like with so many things, ya’ can’t get very high (or far) if you keep changing shoulders to stand on…

The good news is that the wait is over. All documentation and collaborative editing is going to be done with Redmine, the same system which has been driving the Café for some time now. But a few things will change:

• Redmine has now evolved to version 2.0.3, and I’ll be using subversion to easily track updates
• page formatting will switch from Markdown to Textile plus Redmine’s own extensions
• anyone can register to participate, but the process involves an administrator (goodbye, spammers)
• the system supports generating PDF’s, so we can have good web docs and good paper-like docs
• better support for page hierarchies and automatic page lists, i.e. more high-level structure

Also, I found an excellent theme for the wiki, which gives the whole thing a clean look and nice layout. Like so:

Clean, minimal, and compatible with all modern browsers, as far as I can tell.

But this isn’t about good looks at all, really. That’s just an enabler, to finally make it worthwhile to pour tons and tons of my time into this.

And now that I have your attention…

The above has been set up, but it’s very, very early days. Things may get (slightly) worse before they get better – i.e. I’m not going to do much more maintenance on the current Café pages at https://jeelabs.net/ – neither the hardware pages, nor the software documentation, nor any of the other wiki pages or user-contributed info.

The reason to announce this here anyway, is that I want to make a really serious effort to get it right. I would like Physical Computing software and hardware such as from JeeLabs to be maximally fun to explore, easy to get acquainted with, fully open to adopt and tweak, and truly, truly, truly effective and practical. No fluff, no nonsense, but a rich resource which improves over time.

I love writing (heck, 1000+ posts ought to have made that clear by now) and as I said, I’m willing to pour lots of time and effort into this. But I can’t do it alone. You can help by telling me what sort of info you need, where you’re coming from, what style and structure would work well for you, and you can help point out the errors, the gaps, the omissions, the mistakes… or anything you don’t agree with and consider substantial enough to bring up.

You can of course also help a lot more than that, by participating in this initiative to get a really good collaborative documentation site going (I’m willing to beg on my knees, bribe you in some innocent way, or pile up the compliments if that helps). Everybody is busy, but I think there is value in trying to coordinate efforts like this.

To put it all in perspective: this new documentation site is not “my” site (other than providing the infrastruture). Even though I’ll probably be one of the main contributors, it’s not anyone’s site, in that nothing on it should be written in first-person form. No I’s and me’s to wonder about who said what. It needs to become everyone’s site, a live knowledge base, with full and honest attribution to everyone who volunteers to get involved.

Let’s get the focus on audience right. Let’s get the structure right. And let’s get the content right. In that order.

Here’s the bad news (yeah, I know, should normally have started off with this) …

No spotlights on this endeavor for the next three months. No fame. No riches. Only blood, sweat, and tears.

This weblog post will remain the only one to draw attention to this documentation challenge. I’m inviting you to participate and help shape things. I hope some of you will find a suitable amount of time, right now or later on.

Note that I haven’t mentioned “code” until now. That’s not because code is irrelevant. On the contrary – part of this work will be to write new code, redo things done so far, and if possible even to “lead by example”. The same goes for technical documentation and for tutorials which can go far beyond just telling what the code does. And for automatically generated documentation from comments or other text files. It all has a place.

But it’s easy to get swamped by it all – as I’ve been for so long – and never reach a practical point. Best thing for me to do now, is to try and pick a single direction for documentation and run with it. You’re welcome to tie your own interests and efforts into this – I’m sure we can figure out ways to make things work nicely together.

One last point – this isn’t really limited to software or hardware from JeeLabs. To me, this whole Jeelabs thing is just an umbrella to go off and play with “Computing Stuff tied to the Physical World”, wherever that leads to. I use this as basis to try and stay focused (hah!) and keep aiming in a somewhat coherent (hah again!) direction.

Wanna help make the above happen? Email me some thoughts and I’ll set up editor access for you.