A Specification Specification

Raise your hand if you love spec writing. No one? Raise your hand if you like reading a spec written by someone else. Definitely no one. If you think we don't need to improve this situation, you can stop reading now. If you envision a better world, however…

The first question is the same first question for most things - what are you trying to accomplish? End user documentation? Technical documentation? Release notes? Tutorial?

The first corollary question is the same for most things - who is your audience? C-Suite stakeholders? Consumers? QA? Sales team? Architecture level conference paper? Hands-on information for implementation developers? Professional services customization engineers?

Wow! Are we going to cover all of that in one article? Raise your hand if you would really want to read an article that covers all of that in one pass. Again, no one. Yeah, me neither.

So far we have established a broad topic, and a way to not cover it because there would be no audience for that form of expression. This is already better than much of the documentation we have all read.

Login to Read Complete Article.

Bennett Barouch

Bennett Barouch, an executive at eBay, a Fortune 500 company, has been VP of Engineering at a half-dozen startup companies. Work he led is in the permanent collection of the Smithsonian, for Outstanding Achievement in Information Technology. incredible combination of experience.

View more articles


Mar/Apr 2013