Coding by the Beach

These days, I tend to shy away from writing verbose documentation with no breaks. I do that on purpose.

Having worked as a technical writer for a year, I know that the most complete document is not quite the answer in most situations. Even with the most complete document, people who read the document will still come to me to ask where things were. (And it does help a lot in the requirements process, where we are gathering data that will become the goals and constraints of the software project).

People are somewhat dumb by design. They will not look into things if they don’t have to. They would rather complain behind the writer’s back, too, than telling the writer that his document is incomplete (or complete but somewhat disorganized). They only like reading novels or magazine articles for entertainment. Reading 100-page documents is just out of style (or in their formal word, “work-like”).

I thought, hmmm… it doesn’t have to be this way.

These days I tend to choose pictures. A storyboard like this can definitely convey more than a thousand words worth of explanation:

Another way to chart ideas is by utilizing mind-maps. Here’s what it looks like:

From Wikimedia

What do you think? Is written document out of style? Is there a better way to document thoughts and processes, than verbose document writing?