Incorporating documentation into development

There's a long tradition of "fix in documentation" - flaws in software that can't be corrected quickly enough in the software, so warrant a warning or workaround in the documentation. A lot of the time, these issues aren't actually recognized as bugs. The documenters just have to write a long explanation because helping the user work with the software requires one.

Documentation, of course, is often an afterthought, a project that's considered derivative of the rest of the work. Interface designers dream of documentation-free software, and programmers rarely consider documentation their first priority. These issues make it difficult for documentation to improve software, leaving it a passive follower rather than a potential leader.

Documentation? A leader?

Yes, actually. Something strange happens when you need to describe a process in words, and something even stranger happens when you need to describe that process in words you won't be there in person to explain. Add to that the terror induced by putting those words through a printing press for permanence and distribution, and you have a situation that requires thinking through and thinking ahead to survive.

I've known two broad kinds of writers: those who trying to sell (or evangelize) the things they write about, and those who are trying to explain. (There is, of course, a broad spectrum between those.) Evangelists sometimes find themselves forced by the difficulty of explaining their subject to change their views of it, and explainers are constantly looking for better ways to get across the fine points of complex subjects that aren't always consistent or complete.

I keep finding that authors, especially explainer authors, often find themselves trapped by the flaws of their subjects. As writers try to find paths for connecting with diverse audiences, they have to look at their subjects from a variety of angles that go well beyond determining the shortest route from A to B. Architectural or interface inconsisatencies can madden authors quickly. While writing frequently about complex topics gives writers the experience to deal with these problems, seeing the same kinds of problems over and over in different contexts often leaves writers with a strong - perhaps too strong - sense of where the gaps are.

This sense of the gaps is hard to reconcile with the ambitions of those creating the gaps. Documentation is generally meant to paper over the gaps, not expose them to readers. Readers seem to have as limited a tolerance for reading about how software won't actually solve their problems as they do for the broken software itself. I had a great technical reviewer complain about my of "dissing Rails" as I attempted to explain some tricky bits and the reason for their existence. I see similar complaints regularly from other reviewers of other authors, and occasionally they surface in book reviews as well.

The tech world doesn't seem to take writing as a strong credential. Maybe it's a sense that "those who can, do; those who can't, teach", or that writers frequently express themselves in words, not code. I was surprised how much more seriously even bad code was taken than explanations in the XML world, and that had an amazingly literate core community obsessed with specifications. Pointing this out, of course, doesn't seem to change the situation.

"Fail forward fast" is a popular mantra lately. The hard part of it, though, doesn't seem to be the "forward" or "fast" part - the hard part is recognizing and accepting the "fail" part. I can't help thinking that projects that want to get this right would be smart to make people writing about their work a key part of the process, letting them know when they've failed before projects reach a wider audience. It might be a strange reversal of the usual workflow, and doubtless it would be uncomfortable for everyone involved, but it might yield better results.

You might also be interested in:


Reading this, a couple of thoughts come to mind.

First, there's BPMN. Using a tool like Enterprise Architect from SparxSystems (I'm a happy user of the product, that's all), business analysts and subject matter experts can document the software system to be developed in a way that nicely flows through to artifacts like sequence and class diagrams, and hence to code. IMHO, this approach is a huge improvement over text-based functional specification documents (FSDs) driving UML. The "impedance mismatch" between text-only descriptions and UML diagrams can be quite high.

Second, take a look at this: - the latest generation of Knuth's tools, tangle and weave. I've always liked this idea, but I've yet to see anyone actually use it in a production system. It seems to be treated more as an intellectual curiosity than something useful.

For myself, since I currently live in the world of text-based FSDs driving everything else, I tend to write methods like "isExpectedEncounterTypeIdentifiedInTheEncounter(encounterDTO)" and "getExpectedEncounterTypeIdentifiedInTheEncounter(encounterDTO)" where the method name is directly from a statement in the FSD. Usually, I will also grab the bits from the FSD that apply to the method and make them part of the method's javadoc. Methods like this tend to be private, live inside command patterns that implement individual use cases, and make use of lower-level services. This approach is wordy, but it does keep things clear.

I hope this makes some sense.

The problem with documentation and anything written for that matter is that everything is mostly static, boring, non graphical most of the time and doesn't take advantage of multimedia. Take a look at QuartzComposer for example, that's the kind of stuff that really feels like the future of software engineering. Or screencasts for that matter!

One of the curent trends in tech comm is for writers to move into agile teams, and/or to get training in usability and to take formal positions that give them a valid role for critiquing the UI during development. Experience attempting to make a poorly designed interfaces comprehensible to users gives writers a lot of insight into what type of UI designs are usable and/or explainable. At some point, tired of being an explainer of the incomprehensible inconsistenies in the inteface, the writers are ready to take serious steps to change things.

News Topics

Recommended for You

Got a Question?