When you’re doing programming, you have to explain something to a computer, which is dumb. When you’re writing a document for a human being to understand, the human being will look at it and nod his head and say, “Yeah, this makes sense.” But there are all kinds of ambiguities and vagueness that you don’t realize until you try to put it into a computer. Then all of a sudden, almost every five minutes as you’re writing the code, a question comes up that wasn’t addressed in the specification. “What if this combination occurs?” It just didn’t occur to the person writing the design specification. When you’re faced with doing the implementation, a person who has been delegated the job of working from a design would have to say, “Well, hmm, I don’t know what the designer meant by this.” It’s so hard to do the design unless you’re faced… Read more →
EppsNet Archive: Documentation
The Illusion of Control
More paperwork does not ensure greater information reliability or accuracy — it only adds to the non-value-added cost. It only seems that adding more measurement and reporting means better control. The illusion of control may partially explain an obsession with control. — “Ninety-Nine Rules for Managing ‘Faster, Better, Cheaper’ Projects” Read more →
Thought for the Day
Sometimes it is worth trying to find a way to solve problems that doesn’t involve more structure, more meetings, more roles, more documents, more setup. — Daryl Kulak Read more →
Communication Bandwidth
As I’m writing this article, I’m trying to formulate ideas, understandings, and experiences into words. When you read this article, you try to understand what I’m saying within the context of your experiences. In the process of narrowing my bandwidth to words, and you trying to expand the bandwidth from words to your understanding, a lot is lost. No matter how well I write and you read. And, most of us are not superb writers and readers. — Ken Schwaber Read more →
Eliminate Unnecessary Paperwork
If you need to explain something, try mocking it up and prototyping it rather than writing a longwinded document. An actual interface or prototype is on its way to becoming a real product. A piece of paper, on the other hand, is only on its way to the garbage can. — Getting Real, 37Signals Read more →
I Hold in my Hand a 63-Page Requirements Doc
I hold in my hand a 63-page requirements doc . . . We spend a lot of time reworking the requirements doc to reflect the reality of the system that we’re actually building. We also spend a lot of time reworking all the docs that derive from the requirements doc — design docs, UI docs, test plans, etc. — to reflect the changes in the requirements doc. Another way to think of this is that the project is driving the requirements, rather than the requirements driving the project. So why did we create all these incredibly detailed documents in the first place? We have a vast collection of well-documented ignorance . . . Thus spoke The Programmer. Read more →
99 Rules
Here’s a short excerpt from an article called “Ninety-Nine Rules for Managing ‘Better, Faster, Cheaper’ Projects” by Alexander Laufer and Edward J. Hoffman: In a dynamic environment, project management is not about performing according to plan, with minimal changes. It is about meeting customer needs, while coping successfully with unavoidable changes. Therefore, the planning system should be capable of coping with changes. Jesus Christ, if I could articulate even one rule that perfectly, I’d publish it and call it a day . . . but there are 98 more of these! Here’s another one: More paperwork does not ensure greater information reliability or accuracy — it only adds to the non-value-added cost. It only seems that adding more measurement and reporting means better control. The illusion of control may partially explain an obsession with control. A must read! Thus spoke The Programmer. Read more →
Disorganization
We’re trying to figure out a directory structure that lets us organize project documents in a way that’s less confusing than the current directory structure. We’ve got a lot of documents and nobody can find anything when they need it. Thinking outside the box for a minute, maybe a better question would be: Do we really need to produce this many documents? Thus spoke The Programmer. Read more →