Ok, it's taken a few incidents, but I've just got to vent about the state of developer documentation at The Job.
We have, like many places, a wiki for the devs to store documentation about our systems, tools, plans, etc. It's the usual jungle of outdated posts, incomplete references, and even chat transcripts, but the detail that got me today is the abysmal quality of several pages pages - one was the description of a library API, the other was the steps to set up a VM for testing.
The API had a list of the methods for a Java class, but the list was an image capture of a scrollbarred list - not a image in a window with scrollbars, but the static image of the list. So not only was it lazy, it was nearly useless, in that it was neither a set of linkable items, nor text that I could copy to paste into another search.
The directions page was rife with assumptions of context - that I knew what parts of the images pasted into the list referred to, again without giving me text that I could cut&paste for ease of following or modifying. I mean, I'm not necessarily the sharpest guy, but the entire point of the list of directions is to make it clear what to do, even for someone who is unfamiliar with the task.
Please, please, people, if you are writing developer documentation, make it easy for the reader to use your steps, and make sure you give full context.
