My current LUFA Priorities
Another week. Those with cron-jobs synching up their machines to the LUFA repositories every 30 seconds would have noticed a distinct lack of much in the way of work the last week or two. The reason for this is twofold; one, I am right in the middle of my toughest mid-year exams, and two, I currently have a chest infection and so I don’t feel like working. The best part about doing this on a donation/license basis is that I’m not tied down to deadlines.
On that note, I’m not going to set a date for the next LUFA release; my target will be when the Bluetooth RFCOMM code is finished in a state where it can be used by the unwashed masses. Regular releases are important to push out changes to the general public and retain interest in the project, however I’m a big believer of making the releases fit milestones rather than arbitrary dates. Also, since I’ve pretty much only been working on the Bluetooth code since the last release, not having it in a completed state would make for a rather boring update.
Thanks to everyone for their feedback on my last post about LUFA development priorities. I must say I was a little surprised at this one, since everyone seems to be clamoring for better documentation rather than better features. I realize that without proper documentation more features are largely meaningless, but I also though that the current Doxygen-plus-demos system wasn’t all that bad. That’s exactly why I posed the open question however, since a good developer knows to poll the customer and receive feedback when developing a product (or project, in this case) to ensure that it fits the customer’s requirements.
As I said above I’m totally committed to completing the Bluetooth code for the next release, so that will continue to be my number one priority until it is complete, which should be much sooner than everyone thinks. Beyond that I’ll work on better documentation to try to make the project more accessible to new users. That brings me to my next open question; what sort of docs? Do people want a separate set of documentation, or do they want it integrated into Doxygen? Do you want to see tutorials, an overview of USB, or what? What do you imagine when you think of a manual capable of making LUFA accessible to the new user?
Finally this week, I received my shiny (actually, matte, but multicolor) passport. That’s the last component I needed to get my Atmel internship up and running, so it’s all systems go! Come this November/December I’ll be working at the Atmel HQ over in Norway. Damned exciting.
Get well, o wisest & almighty! 🙂
And good luck with your exams!
You should have a wiki!
You also need a page like this one:
http://vusb.wikidot.com/driver-api
but yours will be much longer
There’s also a troubleshooting section there, if people who use LUFA have tips for common problems, a Wiki would be a great place to gather common tips and gotchas
For example, one of the first things I would put there is for people to check where their descriptors are stored, and remind them that they need to use pgmspace functions to retrieve the length of the descriptors
Oh and include a link to http://www.beyondlogic.org/usbnutshell/usb1.htm in the documentation somewhere
Good luck with exams
Don’t make the mistake of mixing the tool (doxygen) with the kind of documentation people need. The tool is irrelevant, just a means to an end. if you like doxygen then use it.
IMHO there is just one caveat. A typical doxygen error is to write as if the reader sees the same things in the same context as the writer while writing. The writer is looking right at the source code, in a context that is obvious to him. The document reader just sees parts of the code, for example, only a function signature, and is not familiar with code details. What is obvious for the writer, because it is right there in the file, is not obvious to the reader.
Typical bad doxygen comments are of the form ‘Function getAbc() returns Abc’ without right there explaining what Abc is, why one might want to have it, what can be done with it, what must be done with it (e.g. free()’d because it is malloc()’d), and in what context it can be used. E.g. first one has to call a few other functions (which one?) before getAbc() returns meaningful data. E.g. Abc becomes invalid after setZyz() was called.
The above things are glaring obvious when looking at the code, as the doxygen writer does, but are a mystery to the reader who reads the documentation because he or she doesn’t want to study the code in detail.
But getting that right just requires some discipline when inserting doxygen comments and is not a fundamental problem of the tool. Other tools (Word …) have other problems.
What really counts is the contents and structure of the documentation. I know you wrote you don’t plan APIs, but what about planning the documentation? A single, easy to find entry point, the current documentation isn’t clear here. A conservative document structure, with the usual documents, like getting started, programmer’s library manual, reference manual, guide to applications/examples, advanced topics downwards from that entry point.
There should be information in each document what the reader should have read before, what prerequisites. E.g. if a configuration according to another document, earlier in the hierarchy of documents, must have been performed first, if certain USB knowledge is required.
A document should have a purpose beyond ‘oh, that is interesting, I want to tell that people’. There is a goal or goals to achieve with a document. Consider planing these goals ahead before spending time to write a document. What should the reader have learned after reading a document?
Is information duplicated and is there a justification for that duplication. E.g. programmer’s guide and reference manual typically contain duplicate information, justified by the different goals. One should enable the programmer to learn the API, the second should allow to find details when roughly knowing the API.
A document should fit into in an overall structure. Ideally, all documents form a tree, with the, for example, Getting Started guide at the top, more and more details at the hierarchy levels and typically no circular cross references.
All that is a lot of work, and sometimes writing code is easier than writing documentation.
Good luck with your exams and congratulations for your internship.
[…] TPosted on June 29th, 2010Thanks everyone for their input on the future of the LUFA documentation I asked about last time – some very good feedback posted, and I’ve moved the discussion over to the LUFA […]