Great products need great documentation

In many cases, a poorly documented product feature may as well not have shipped. Time poor server administrators are more likely to use a search engine to figure out how something works than they are to faff about exploring the interface.

Sure, enthusiasts will discover features. However, what counts as “intuitively discoverable” to the geeks on a product team isn’t necessarily “intuitively discoverable” to a server administrator who is under constant time pressure.

I remember reading somewhere that Steve Jobs was of the opinion that documentation didn’t matter much and that a product’s interface should lead to users to intuiting everything they needed to understand about the product.

The idea of the product that teaches you how to use it is wonderful. It’s also a platonic ideal. An idea that’s perfectly comprehensible when we hold it in our mind, but almost impossible to implement in the real world.

I’m not the only one that has noticed vendors skimping on the production of great documentation. In the past there seemed to be an implicit understanding that a great product needed great documentation. To put on my “Grandpa Simpson” hat for a moment: Software used to ship with huge door-stopping paper manuals. But then, to be more efficient, the manuals were made electronic. Then the documentation moved online.

And since it moved online, it feels like documentation has started to atrophy.

The amount of documentation has felt like it’s decreased, in volume and perhaps in quality.

It often seems as though I'm more likely these days to find the answer to a thorny problem with a product posted on an enthusiast's blog than I am to find the answer in the vendor’s publicly posted documentation.

The Jobsian¹ attitude about feature discoverability is fine when one is thinking about simple consumer oriented products. It’s not all that great when it comes to complicated products that are about as intuitive as the startup routine for a nuclear submarine.

Vendors display a great amount of enthusiasm for regularly “changing the paradigm”. But the people that need to work in a vendor’s brave new world can only be inculcated in that new paradigm if high quality documentation and learning materials are already present.  

If the documentation and learning materials are scarce or incomplete, only a small number of exceptionally motivated individuals, rather than the plurality of a vendor’s customer base, is going to understand and thrive in the brave new world the vendor is trying to create.²

Great products need great documentation and learning materials. Vendors need to ensure that it gets created and not hope that enthusiasts will create it for them. If great documentation and learning materials doesn't exist, then only a small number of customers are ever going to use a product to its full potential.

---

1. Assuming I’ve attributed it correctly

2. Sure, being motivated to figure it all out yourself ensures employability. However, as I mentioned in last week’s blog posts about learning, the vast majority of people don’t learn to swim by leaping into the deep end of the pool on the basis of reviewing a couple of conferencing sessions and figuring out how to float, tread water, paddle, and kick once they are already wet.

---

Orin Thomas is an MVP, an MCT, a Microsoft Regional Director, and has a string of Microsoft MCSE and MCITP certifications. He has written more than 30 books for Microsoft Press on IT Pro topics including Windows Server, Windows Client, SQL Server, Exchange, and System Center. He is an author at PluralSight and is a contributing editor for Windows IT Pro. You can follow him on twitter @orinthomas