Programmers Are Writers

First thing you have to buy is that ALL programmers should become good writers. It is important not only to communicate with the computer your ideas and intentions, but also to other human beings (specifically those who will read/adapt/modify your code).

DonKnuth developed his LiterateProgramming technique because he believed that programs should be written for people to read. This is also behind The ElementsOfProgrammingStyle (BrianKernighan and PjPlauger).

The Pattern community takes this one step further: Design should be written for people to read.

CaseTools, DocumentationGenerators? and standard forms (such as MilitarySpec2167) are not replacements for good writers.

Software Engineers who do not approach documentation with the same care as they approach code are dangerous. I don't document my hacks and toy programs, but my tools and systems must be adequately explained or else they won't be used.

-- ToddCoram

In a utopian world, programmers are writers. The reality in the shops that I have worked in and visited, even with case tools, documentation is scarce. What is there is often incomprehensible largely because of the mind-set of the programmer. When a programmer is writing code, she/he knows the reality being defined intimately. They frequently are not able to back out of that intimacy and express it with the simplicity that is required for the next programmer's attempt at an intimate encounter. A consultant that I am doing work for expressed the corporate reality best. While designing and building a small system I was adding documentation and began work on a user's manual. His comment? "The clients that I have are not interested in paying for documentation, they expect the next programmer to get into the code and figure it out if necessary. Forget the documentation, they don't want to pay for it."

Oh my, he isn't a programmer friendly type is he? I think you might be unpleasantly surprised by the number of consultants, managers, supervisors, project leaders and programmers cling to this mode of operation. The bottom line keeps floating to the top of the priority list....if it costs money and i don't need it, don't waste time on it. In this age of continued down- and right- sizing, there is little time or money to be spent on the problems of tomorrow. We code for the day, not for correctness.

It's easy to fix all this, right? Just convince them of the importance of documentation. Yes, educate them! OK, I'm not the total cynic. It will work for some, but the majority won't buy it unless you like writing on your time, out of the goodness of your heart and compassion for the next poor guy that has to work on your code.

-- BillMeecham

Here, here! Coming at it from the opposite end,that of an aspiring tech-writer, documentation tends to get short shrift. In what I've heard, and from my limited observations, the documentation and the task of us tech-writers is often the last consideration. People who would, rightly, pitch a fit of unheralded proportions if asked to bang out code for a project over, say, a single weekend will think nothing of asking tech-writers to do the equivalent with their job. "Here you go, we have a few days before this needs to be released as beta, you can pull something together?" We certainly try, but it's frustrating. And frankly, when we write bad text we look just as bad as you do when you write bad code. It would be nice if our co-workers would realize this. I'm a cynic too Bill, but here's hoping. Back to lurk mode for me -- DanielleOviatt

In the end, the most accurate (if not the only!) documentation is often the code. Getting folks to write legible code, let alone good written documentation, can be difficult. Fortunately, there's a leverage point, which is to nudge people towards the mindset that Programs exist first to inform people, and only second to inform the machine. A culture or process that includes peer review helps, since it provides a built-in reminder that other eyes will pass across the code.

Sigh. We're expected (or expect ourselves) to function well across an incredibly diverse set of problem domains and levels of abstraction.

-- DaveSmith

Trust the terrain, not the map. -- JimCoplien

Trust the terrain, not the map - when traveling short distances by foot. Bring the map with you, if you are travelling around the world. -- MichaelBeedle

Good writing, at least in this context, is the ability to take a complex object, such as a piece of code, and explain it succinctly and clearly. It's an abstraction, in the same sense that statistics are abstractions: no one can understand large volumes of data; statistics are used to extract features of the data. So, (aside from documenting specific, un-obvious program statements), documentation should be a high-level abstraction of the code.

Beyond a single high-level description per module, I discourage in-line comments for the simple reason that they are never up-to-date. Over time, in-line code leads to what I call ThePalimpsestEffect.

-- MaxRahder

I know we are writers. I just wish more of us were READERS! -- Patrick Logan

Is separately maintained code documentation the Cliff Notes of programs? And, is that a bad thing? It certainly doesn't impart a deep sense of understanding.... ;-) -- ToddCoram

Of all the separately-maintained code documentation I've seen, the most effective by far was a one page E-R diagram of an underlying data model. The runner-up was a pair of one page Class Relationship diagrams (of the Booch variety). The E-R diagram was drawn during design, and was a guiding beacon for development. The relationship diagrams where drawn after the fact, and parted the fog around a complex area of a system. Both were succinct and to the point; both avoided turgid prose. -- DaveSmith

See TechnicalMemo