Computing stuff tied to the physical world


In News on Jun 20, 2012 at 00:01

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:

Screen Shot 2012 06 19 at 22 30 35

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 – 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.

  1. It sounds very ambitious and challenging. I’d be happy to help in the limited time I have but right now I cannot promise a solid contribution. Which made me think the following: I wonder if choosing mercurial or git instead of svn would help people to participate. The model with pulling changes has proven to lower the threshold in participation in open source projects so maybe it would help here too?

    Both you and the editors keep conrol over the quality but the effort to absorb the contributions should be lower. And gihub (although mercurial is arguably easier to use) has already all the tools to give credit to contributors which is especially important for newbies in open anything.

    Just my two cents…

    • See, that’s what bad docs can lead to: all the code is on GitHub right now. You’ve been fooled by stuff on the Jee sites which is way out of date and still pointing to my old svn repository…

      Great point about to pull model. I can see it happening with the source code itself. The key will be to find the magic balance between git-based contributions and wiki-based editing on a shared spot on the web. Couple of ways to go – with Doxygen and Jekyll (GitHub’s static webpage generator) both useful options to consider in this mix.

  2. let’s also make a “docu-complaint” corner in the forum so we can gather and analyse what items we should focus on.

    • New topic? Separate forum area? Use GitHub’s issue tracker for this? I’m also considering setting up new feedback mechanisms in the new Redmine site. But that won’t be out in public until the site has some substance.

      So many ways to go, so many ways to dilute the whole effort and fizzle, so many implications…

  3. In relation to content, I like your idea of other information besides just the “jee” stuff. Along the lines of your Toolbox series, I think doco on some the the supporting infrastructure of the physical computing would be useful. An example would be DSOs.

    You seem to be really getting the most out of your Hameg purchase with the articles you have been posting. I’d love to learn more about mine (HMO744) and how to use it relating to the physical computing. I’ve found the going pretty steep, and I’ve like to contribute what I’ve learnt, and in turn learn from others.



    • Adding some posts about getting more out of an oscilloscope sounds like an excellent idea. Preferably tied to some meaningful use cases. You say HMO0744, did you mean HMO0724 – that would be virtually identical to the one I’m using.

  4. For the sake of completeness, there is also the “literate programming” approach. For people who like writing prose (like jcw) it can be very rewarding.

    If you want to try it I would suggest trying nuweb – it is language agnostic and compiles across different platforms.

  5. JCW, yeah I meant HMO0724. They are an incredibly powerful piece of equipment, and you are really left to your own devices on how best to use it.


  6. Good timing: I just posted a JeeNode review on my blog. I really, really liked them and the only negative thing I had to say was that the organization of the documentation could be improved.

    I think the Jee architecture would be fairly bulletproof with the documentation improvements you’re talking about.

Comments are closed.