Let’s face it – some parts of the JeeNode / JeePlug documentation isn’t that great. Some of it is incomplete, too hard, missing, obsolete, or in some cases even just plain wrong.
I think that the fact that things are nevertheless workable is mostly because the “plug and play” side of things still tends to work – for most people and in most cases, anyway. You assemble the kits, solder the header, hook things up, plug it into USB, get the latest code, upload an example sketch, and yippie… success!
But many things can and do go wrong – electrically (soldering / breadboarding mistakes), mechanically (bad connections), and especially on the software side of things. Software on the host, but most often the problems are about the software “sketch” running on the JeeNode. You upload and nothing happens, or weird results come out.
Ok, so it doesn’t work. Now what?
There’s a chasm, and sooner or later everyone will have to cross it. That’s when you switch from following steps described on some web page or in some PDF document, to taking charge and making things do what you want, as opposed to replicating a pre-existing system.
To be honest, following instructions is boring – unless they describe steps which are new to you. Soldering for the first time, heck even just connecting something for the first time can be an exhilarating experience. Because it lets you explore new grounds. And because it lets you grow!
As far as I’m concerned, JeeLabs is all about personal growth. Yours, mine, anyone’s, anywhere. Within a very specific domain (Physical Computing), but still as a very broad goal. The somewhat worn-out phrase applies more than ever here: it’s better to teach someone how to fish (which can feed them for a lifetime) than to give them a fish (which only feeds them for a day).
IMO, this should also drive how documentation is set up: to get you going (quick start instructions) and to keep you going, hopefully forever (reference material and pointers to other relevant information). A small part of the documentation has to be about getting a first success experience (“don’t ask why, just do it!”), but the main focus should be on opening up the doors to infinitely many options and adventures. Concise and precise knowledge. Easy to find, to the point, and up to date.
Unfortunately, that’s where things start to become complicated.
I’m a fast reader. I tend to devour books (well, “skimming” is probably a more accurate description). But I don’t really think that thick books are what we need. Sure, they are convenient to cover a large field from A to Z. But they are reducing our options, and discourage creative patterns – What if I try X? What if I combine Y and Z? What if I don’t want to go a certain way, or don’t have exactly the right parts for that?
This weblog on the other hand, is mostly a stream-of-conscience – describing my adventures as I hop from one topic to the next, occasionally sticking to it for a while, and at times diving in to really try and push the envelope. But while it may be entertaining to follow along, that approach has led to over 1000 articles which are quite awkward as documentation – neither “getting started” nor “finding reference details” is very convenient. Worse still, older weblog posts are bound to be obsolete or even plain wrong by now – since a weblog is not (and should not be) about going back and changing them after publication.
I’ve been pondering for some time now about how to improve the documentation side of things. There is so much information out there, and there is so much JeeLabs-specific stuff to write about.
Write a book? Nah, too static, as I’ve tried to explain above.
Write an eBook? How would you track changes if it gets updated regularly? Re-read it all?
A website? That’s what I’ve been doing with the Café, which is really a wiki. While it has sections about software and hardware, I still find it quite tedious (and sluggish) for frequent use.
I’ve been wanting to invest a serious amount of time into a good approach, but unfortunately, that means deciding on such an approach first, and then putting in the blood, sweat, and tears.
My hunch is that a proper solution is not so far away. The weblog can remain the avant garde of what’s going on at JeeLabs, including announcing new stuff happening on the documentation side of things. Some form of web-based system may well be suited for all documentation and reference material. And the forum is excellent in its present role of asking around and being pointed to various resources.
Note that “reference material” is not just about text and images. There is so much information out there that pointers to other web pages are at least as important. Especially if the links are combined with a bit of info so you can decide whether to follow a link before being forced to surf around like a madman.
The trick is to decide on the right system for a live and growing knowledge base. The web is perfect for up-to-date info, and if there’s a way to generate decent PDFs from (parts of) it, then you can still take it off-line and read it all from A to Z on the couch. All I want, is a system which is effective – over a period of several years, preferably. I’m willing to invest quite a bit of energy in this. I love writing, after all.
Suggestions would be welcome – especially with examples of how other sites are doing this successfully.
Tricky… Have a look at http://www.pandamian.com/ This is what powers MBA mondays: http://mba-mondays.pandamian.com/tableofcontents/ I find the organization of the content great! and it’s exportable as a ebook.
What about a real wiki system? That way, all the people at JeeLabs doing stuff with JeeStuff can create and update pages. You could even get a wiki system that has “moderation” for a group of people you select and trust with it. The cafe is not exactly a wiki with a lot of functions and it’s counter intuitive, so almost everyone is scared of immediately.
As for documentation for the code, take a look at what Doxygen can do, but there will probably be better systems out there. And everyone can submit documentation patches to you on Github….
For starters: I think it’s a good idea to seperate the “plain code documentation” from the how-to documentation. The first type would be suitable for a doxygen generated webpage, where the latter could be placed on a wiki system. (Maybe even the real wikipedia? But we have no control over that….)
Remember: You don’t have to type all of this on your own, even if you’re willing to invest a lot of time. You should just figure out a method to lower the bar to contributing.
I totally agree with Vliegendehuiskat, in addition I would add, making the blog articles search more friendly (return a list of titles not every page that matches.) Also some sort of indexing of all of the blog articles (possibly requires going back and tagging them) within an expanded wiki would also be useful. That way the massive resource that is your weblog can be tapped into more easily.
And yes I think you could leverage off the broader community in this endeavour ;-)
Doxygen tends to work well for me, as it tells you what you haven’t documented, and if you ever make changes then you can explain it in the file you’re already editing. It’s also very useful for jumping between classes if you need to look up a particular parameter etc.
It’s not very pretty – but I think most of us would take accurate over pretty any day.
Thanks for the suggestions. I’m still struggling…
Although I haven’t used it much, I find this (JavaScript-based) approach more direct: http://visualjquery.com/ – hierarchical as well as alphabetic browsing, and extremely quick to navigate. The advantage is that you’re not constantly descending and backing out, at least not as explicitly. But this can also be a disadvantage, since this may not easily map to a linear PDF / eBook format. The chunks you navigate to are quite small.
The Drupal “book” approach also seemed like a good idea. But it doesn’t have easy wiki-style linking out of the box.
Yet another option would be to add reference material as a tree of pages in this WordPress site. It supports multi-user access.
The best approach no doubt also depends on the type of info. Technical reference material vs getting started docs, for example.
To be honest, I haven’t seen a real mind-blowing format and approach yet.
@Tim: I don’t think I can do much about the way WordPress implements search. But adding lots more tags, and perhaps a tag cloud, might definitely be a way to improve access to all those posts. Also, every once in a while I update the Alphabetical and Chronological index, but that’s a manual step right now.
Jcw, let me say firstly that I find your site(s) more helpful than many others that I’ve tried, I’m one of those people with a keen interest in all things tech and enjoy making things do stuff. I like the way I can find out about the hardware and all the links are there to get more information, I.e. example sketches and lists of functions. The bits I struggle with, and that may be good because it makes me learn, is understanding some of the code as I’ve no formal education in C, I learn as I go. Maybe some more explanation in code would be a help. I think that putting the information all on one site might help, it sometimes feels fragmented. I would like the Wiki approach as then other people could submit updates to the older sketches to bring them upto date. The biggest positive for me is the really helpful forum you have with some good contributors always willing to help. In summary, if you do nothing then it’s still one of my favourite sites and if you improve it then it’ll be even better.
“Real wiki system – how does this differ from Redmine: syntax? layout? interface? features?” Basically I mean all of those. The syntax of Redmine is a beast to master because it’s not intuitive when it comes to creating lists etc. The layout is also not too nice either. The interface is ok, but could be better and I’m missing a lot of features compared to the “real” wikipedia and simmilar systems. But there is one mayor point that you’ve missed: The point of a wiki is that everybody should be able to add stuff to it. If everyone can add stuff, the documentation can get outside the “JCW” box which might be confusing at first. I experienced asking myself the question “what did he think when he was writing this?” Most programmers will be able to get into that kind of mindset, but if you don’t have a lot of experience, this is a less obvious situation.
GitHub has a wiki function that might solve this problem, because everyone can submit pull requests and you can still keep thing in check. You could also set up your own wiki system (not GitHub) to do stuff like this.
“Doxygen – is this really so convenient as reference? (example)” Doxygen is far from perfect, but it works quite well for a lot of people and some really big projects. It might look ugly, but it is very ergonomical in a “can I find what I’m looking for” manner and it’s quite simmilar to javadoc. You can also merge the documentation with the code and it’ll tell you what is documented and what not.
visualJQuery is nice, but unusable for people that use webbrowsers on TTY-sessions from time to time (me for example). There are also some big differences in javascript handling on different browsers and browser builders might introduce new bugs into it by accident. One more, very important thing about VisualJQuery: You can’t (easely) point to, or get a pointer from a resource by using a simple URL. Each one of these arguments raises the bar on USING your documentation. You should look for the system which has the least problems. It’s also from this point of view that I suggest using two different systems for code-documentation and howto documentation. A mental seperation is easely made for the readers.
I suggest we create a brainstorm on this on the JeeLabs forum about this topic btw.
For reference manual documentation, I prefer sphinx (http://sphinx.pocoo.org/) over doxygen quite a bit. I never tried to use it to document C / C++ code, but it is supported.
What I’m often after, is the phylogeny tree of your stuff (trunk on top, leaves down). What came first, what has been a descendant. In walking up the tree, one finds what JC assumes is common knowledge (as it has been discussed before), walking down the tree shows later improvements and explorations. If this is shown visually, one can easily detect that there was a change in a particular approach for some reason (ie. new board version, new IDE version). By traversing the branches, one can easily find the catches for an approach and more recent versions (which, as you notice, is a problem in a blog). By comparing the branch level with one’s own (board, IDE) version it becomes apparent if first newer development should be read, or that certain hardware changed.
A wiki here could help in that people can add relevant pointers/links and thus create a tightly woven web of information. Discussions on the blog rightly close after a certain amount of time, while the web and the wiki keep evolving. A cross reference between the blog and the future wiki would be very welcome, even if it is a one-side-editable-only “cross” reference.
Read the blog, jump to the wiki and find all relevant up to date information on this blog posting in one place. Ordering of information in the wiki then is of major importance.
As for a workflow that can frequently update a set of documents, that can produce pdf, html, epub and dozens of other formatted output documents, have a look at docBook and Calibre. DocBook was developed for maintaining documentation in xml, Calibre can convert between many formats.
Hi eljonco, I also immediately thought of going the DocBook way, but on the other hand there is no such thing as a nice Workflow-Environment for Docbook that you could entrust to multiple users… The closest thing to automating the setup for Docbook, especially on windows was eDE, but that seem to be abandoned for some time. Then there is still the question which editor to use. I would love some web-based solution to that.
Anyway the basic point for something like Docbook for me would be not to have to think about formatting this and that, do i underline this… and so forth. You define layout and formatting once and all the other time you just go to work and describe, that’s the beauty of it. Whenever you work on some plug and find the doc’s don’t work for it, then you should be able to dive into it and just amend it.
Concluding on this: I think a good approach would be to keep the wiki-character alive with just it’s way of markup, and find and/or develop some interface to transform that into xml-Representation that could easily be put to multiple output-formats (epub,pdf,mobi).
I also agree with Vliegendehuiskat. Perhaps you could separate it into a static part (where only you add stuff) and a real wiki part (where anyone who is registered can put some stuff).
I am rather new to the Jee stuff and I often had a hard time finding the necessary information. Sometimes the info in the cafe was outdated or not there. Then I had to search the blog or the forum. Both typically produced a high number of hits. Mostly noise for my particular problem.
After I finally had figured out the solution it would have been close to no extra work to write a few lines in the wiki.
Another thing that I really miss are more detailed tags of your blog posts e.g. RFM12B, power topics, sensors, i2c, pwm, …
This would make the retrieval of blog posts dedicated to a particular problem much easier. I browsed through all of your blog posts recently and bookmarked them in different folders. You and Tim already mentioned it. And I just would like to encourage you to do it.
As a starter on JEENode and seasoned software engineer, I find the website and wiki very usefull. Some findings in using the site for about 4 weeks now:
1. I would like to know if blog articles or statements made earlier are out of date or changed. You could annotate them quite easy if in writing and publishing a post, related post are shown (by tags and keywords so you could add a warning).
2. Hardware documentation I have found is ok, but not very extensive. For example I have been struggeling to find out:
2a. Is it ‘safe’ to put 5v on the Carrier Board power input and if so, do I need to supply 3.3v to the connected JeeNode or is this taken care of by the some circuit.
2b. Is it ‘safe’ to connect the USB-BUB to the JeeNode if 5v is connected to the Carrier Board.
2c. Why are there capacitors on the images of the Carrier Board and not provided on ordering one.
2d. What types connections are supported on the JeeNode, there seems to be a very extensive amount of options, but I can’t seem to find for example patterns or connectors for the batteries/VCC/+3v connectors. I would very much like to have images and short item lists used by users on connecting JeeNodes to the environment.
As you can see I’m not an electronics engineer and not keen on connecting just a bunch of wires, but want to make sure I don’t destroy the precious hardware :-).
So kudus for the great work so far.
I would be happy to offer support on revising any content related to hardware as I find stuff out. For example on Php.net there is a possibility to add user comments to the authored content.
Furthermore a great indexing and search engine would help!
Kind regards, basm
For static content with controlled write access you might consider Octopress (http://octopress.org) under version control (git, hg). An extra feature is that you can include code from separate files so there is no need to manually type code into the post.
+1 for a ‘real’ wiki.
There are some interesting projects going on but most of them are buried somewhere in the forums. Wouldn’t it be great if everyone registered could present his (or her) projects somewhere and discuss it with others, keep track of changes and update it while the project grows?
This would make a great documentation and distribute the workload a bit.