“Out of intense complexities intense simplicities emerge.”
Dear reader, let me ask you a question…. or maybe more than one.
If you engaged a consultant on a $1m assignment and they gave you a report on a single sheet of paper, would you feel aggrieved?
Now what if that single sheet held a formula that unlocked the cure for cancer? Would it be worth $1m now? Or more even?
So why in our industry do we feel the need to create vast volumes of documentation? Is it because we’re insecure in the content we unleash on the world? Do we have to plump it out to feel justified in garnering the customer’s investment?
Is a 142 page report more likely to be pored over word-for-word or an 8 page report? How about if the report were instead a quote or a contract?
By rights, an OSS implementation guide should be concise and clear so that the implementer can deliver the solution quickly and efficiently. Dot-points, diagrams, code snippets. But many projects feel the need to document the life out of everything. Interface specifications that reach hundreds of pages. Contracts that reach thousands.
If documentation length is inversely proportional to the number of readers who will give it attention, why do some vendors create OSS quotes that are so long? Does it mean that they don’t feel that they’ve established enough credibility during prior discussions? Have they not developed enough trust?
In doing so, are they diluting the core messages that they’re trying to deliver? If it’s their implementation documents, are they just a form of procrastination, talking rather than doing?
I’m being intentionally long-winded. The real message is less documentation, more delivering!