Thursday, January 8, 2009

Making developer docs more accessible

Java EE - crxdeploy/build.xml - Eclipse SDK - /Users/sethgottlieb/Documents/projects/clients/time_interactive/development/crx-clean-ab
Uploaded with plasq's Skitch!


What do developers hate more than writing documentation? Writing documentation that nobody will read. I think everyone has been in a meeting and heard someone complain about needing some information that they didn't even bother to search the wiki or document repository for. But what if the documentation was already in the developers face?

New
Uploaded with plasq's Skitch!


A few weeks ago, a client turned me onto "Cheat Sheets" in Eclipse. Those are the little instructions that appear on the right-most frame of the Eclipse IDE. You may have used one of these Cheat Sheets before (and not known what they were called) but you probably didn't know how easy they are to create. Simply choose the "File | New | Other" menu option and then, under "User Assistance," select Cheat Sheet. This will give you a simple editing tool to create step by step instructions. The underlying XML is very simple so you can also just use Eclipse XML editor if you want to.

Java EE - crxdeploy/testing.xml - Eclipse SDK - /Users/sethgottlieb/Documents/projects/clients/time_interactive/development/crx-clean-ab
Uploaded with plasq's Skitch!


This form of documentation is best for things like development environment setup. It is not so great for API or architectural documentation. It assumes that the developer is using Eclipse and has been able to check the appropriate source tree out of the source code repository because the documentation is stored within the project. I would use this in conjunction with a README and INSTALL file. README would be used for information about the application (version, usage, recent changes, open issues). INSTALL would be for someone installing the compiled application. The Cheat Sheet(s) would be for developers that are getting their Eclipse environment together.

Is anyone else using this feature? If so, have you found it effective?