Creativity helps finding new solutions to old problems, and lets you find better ways of doing things. Of course, simplifying processes isn’t itself simple: as Albert Einstein supposedly said “Everything should be as simple as it can be, but not simpler”, or Jazz’s own great bass player Charles Mingus thought, saying that creativity was “making the complicated simple.”

So, let’s now consider a point that sometimes is left behind: how do you create documentation? If you ask around, most developers will tell you it’s not a well appreciated task, considered to be time demanding and little rewarding, so there’s a good place to look for some simplifications, according to Mingus!

The real issue to consider is actually not documentation per se, but rather communication. Documentation should be written only to further the goals of having better communication within (and, when you do a Knowledge Transfer, also without) the team, and that task can be considered in an evolutionary way, the same as with actual code, with reviews and tests!

An important question is “do you NEED such-and-such document?”, as opposed to “do you just WANT or HAVE TO PRODUCE it?”. Since developers often eschew documentation, work out with them what kind of documents are actually useful for the team, and look for ways to produce them with as much ease as possible. Also consider that it’s been often said that well written code (including automatic tests, as we saw in note #5) is better than static products — the acronym POD (“Plain Old Documentation”) has been mentioned in this context.

A guiding point should be “Travel light”, and look for ways to do with as little documentation as possible; remember that a priority is to build code! However, strive for high quality documents, possibly linked to code and other development artifacts, to help not only the current development work, but also increase the chance of success in future further developments of the current system. Remember that a typical purpose of documentation is to become a “Guide to the New”, providing both global context and local concepts, so newcomers into a project can understand both the main view and the particular details.

Study your current life cycle, no matter what methodology you use, and determine at which points it is appropriate to create documentation, and to eventually update it. Writing comprehensive, full, large amounts of documentation, doesn’t ensure the success of a project; rather, it tends to make its failure more likely! After all, and to go to an extreme: what kind of system will you get, if you insist on having programmers write documentation all the time instead of coding?

So, remembering that all projects and systems have their own unique needs in terms of documentation, follow Mingus’ advice, simplify everything as much as possible!

PS. Charles Mingus made the bass become a solo-ing instrument, instead of a second line one: check out his “Haitian Fight Song” and listen to the powerful sound he produced!

Leave a Reply

Your email address will not be published.

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>