Subscribe to our mailing list

* indicates required

Sunday, March 29, 2009

Where did all the documentation go?

From time to time, I find myself lamenting the sad state of technical documentation today. What's sad about it? Mostly the fact that it is going away.

I try not to be sad, because most things that go away, go away for good reasons. Documentation is going away for many reasons. But I fear few of them are good.

I think there are two main reasons for the steady disappearance of product documentation. One is that documentation is just plain expensive to produce. In my last documentation job, we had a combined doc team (across 3 geos) of around 20 people to produce user guides, admin guides, help files, release notes, developer doc, etc., for a J2EE-based suite of products that comprised somewhere around two million lines of Java code. It took a little over a year for our extended group (R&D, QA, Doc, project management, others) to crank out a major upgrade, so if you figure $80K per doc-team member (way too low if you consider HR and other burden), that's well over $1.5 million to create updated doc for a major release of a J2EE product. And that's before factoring in the enormous cost of localization.

Documentation is a huge cost factor in software development, and companies are looking for ways to trim costs. If you cut back on product doc and customers don't complain, there's a temptation to keep cutting. Eventually you end up with software engineers writing bits of doc because all the tech writers were laid off, but there'll be one guy who didn't get laid off who has to work like heck to wire it all up and make it continue to look like professionally written doc.

The other reason doc is going away is, who has time to read it? People expect to be able to use a product immediately. Which is fine if the product is so well designed, so "self documenting," that it needs no doc. But when is that ever the case?

What do people do, though, now that so many products come with so little useful documentation? The first thing people try is the Web, of course. If there's a wiki with good info, that's what people will gravitate to. But wikis have two problems, typically: spotty coverage, and flat organization (making it hard to find things).

If there's no wiki, customers will go to the user forums. This can be an excellent source of info, but again, the problem is one of organization and findability. The best information in the world is no good if you can't get to it.

When busy people can't figure out how something works on their own, what then? Well, in the case of complex enterprise systems, "what then" is classroom training, quite often. You send your key people to classroom training, and they come back and transfer knowledge to others in your organization. From that point on, it's the help desk that bears the brunt of the burden.

It's a sad state of affairs in some ways, but as I say, I try not to be sad about it, because there's no turning back the hands of time. There's no going back to the days of comprehensive, professionally written, properly indexed, nicely formatted, easy-on-the-eyes technical documentation. And after all, the software companies do have a legitimate point (speaking in a business sense only): If you can get away with not giving customers lavish documentation, why should you spend the money to produce it?

Of course, some companies do still invest heavily in producing good documentation. Some of the biggest names in the business are in that camp. But those are the exceptions.

I can think of one scenario in which it would make sense for documentation to go away, and that's if software suddenly became so self-documenting that there's no real need for documentation. Very little enterprise software falls in that category.

Ironically, the main beneficiary of all this is probably Google, the everything-gateway for doc. With the decline in packaged documentation comes (inevitably) more clicks for Google. Google itself, of course, is self-documenting.

Maybe that's where it all ends. Maybe Google is where doc goes to die.


  1. Anonymous6:51 AM

    Sad decline in product support for sure. A key aspect of good documentation is not the writing but the knowledge organization, the imparted usability of the knowledge. When ignorant, immature, or brutal management declines to sustain this form of product support, I fear a general decline in quality attends. I expect that the writers of enterprise software in ancient Rome faced the same problem before it all collapsed.

  2. Interesting thoughts. I think you're right on the money when you spotlight that companies will continue to take away features that users don't complain about.

    Perhaps the next big innovation in software will be some type of self documenting Wiki that programs can tap so that users can supply their own tips and hints.

    Message boards are great a combining user knowledge but as you point out -- they're just so spread across the web that they really beg to be fully integrated.

  3. Good post... But in way that you said, is like to produce all software documentation in one step and for specielized people... In my job, we have the same problem, but one thing that i think is that in a agile development environment, where all are considered software engeenering, the documentation could be produced for the developers,while procude the software funcionality... Did the software change? Change the documentation in same time...

  4. Two things went through my mind reading this: “May our execs never read this” (we’ve been putting “more* resources into docs recently) and “This is like what’s happening to print news.” Maybe I’m just obsessed with what’s happening to print news. Lately I wonder if newspapers can generate leads for other income-producing ventures. _The Guardian_ is doing that with online dating (squirms snobbishly). All kinds of companies do that with blogs. Can our docs do that? I mean, more deliberately than they already do?

  5. Maybe it's that the majority of documentation I've read has been written by programmers, but it's always a rare joy and thrill to find some particularly good material. Reference information is generally easy to find or generate, but concise overviews on the bigger picture (more than just the sum of the parts) is usually missing. This is why I'm still buying technical books where I can.

  6. This comment has been removed by the author.

  7. greatfog2:50 PM

    DaveK's got your documentation right hete!

  8. Great post!

    As a professional technical writer-editor for the past 27 years, I've watched the decline of respect for technical documentation from the inside. I've watched as companies have cut costs by reducing the number of writers, editors, and other documentation support personnel on staff. I've watched as companies eliminated their documentation staff entirely and outsourced the positions to contracting agencies for way lower rates and no benefits such as health and retirement options. I've watched as companies tried to reduce costs even further by sending the documentation jobs (and even the engineering jobs!) to places that pay their engineers and documentation personnel a tenth or less than the going U.S. rates for the same positions (whether or not they can handle quality work or not). This saves money, but wipes out local workers in that industry who support the U.S. economy with their mortgages (which are now hosed) and other purchases (which they can't do much of anymore -- if they've been laid off).

    Programmers are skilled in programming. Engineers are skilled in engineering. Writers and editors are skilled in producing quality documentation. Programmers shouldn't be expected to do documentation for their programs. Engineers shouldn't be expected to produce documentation for their projects. Let the writers and editors use their skills to free up the programmers and engineers to do what they are best at doing.

    Your idea of "self-documenting" software applications (or engineering products, for that matter) that are intuitive and so well designed that documentation is a minor need is a good one. I've had the good experience (before documentation went away) of participating as a writer/editor on an engineering team when they were developing a product. I provided the "human-factor" and "usability" input. I commented on the positioning of the controls (the buttons and switches, text boxes, and so on) from a "user's perspective". I went into the test labs to verify that the documentation would reflect reality. The final product was something we all could be proud of. This company still produces their equipment and software in much the same manner. But it is more and more rare.

    Thanks again for such an enlightened post. I'm making a point to link to it from many of my blog posts and websites. What you have stated should be required reading by corporate management.

  9. As a research-chemist-turned-technical-writer, as well as a person who spends 8-12 hours a day using various computer products, I'm more than saddened by this trend. All well and good to say docs should migrate to wikis, but what are the poor users to do until that happens? Without adequate (I've given up expecting 'good') documentation in the form of manuals, tutorials, help systems and wikis, users waste more time on trial and error than companies/businesses can afford.

    Just think how much more productive we would all be if the information we needed was available in the first place we looked for it.

    The best documentation I've ever seen was the stuff we produced while I worked at a company with customers all over the US and in several other countries. Customers had multiple options for finding complete and accurate information and instruction on software and business procedures: Excellent printed manuals (also available as pdf docs), thorough context-sensitive help systems, an extranet (intranet for in-house software) with detailed step-by-step procedures, and a superb tech support staff.

    That company took documentation seriously, including all forms of documentation in alpha and beta tests for new products and upgrades to existing products. My experience with the in-house software, documented by another team, the documentation reduced frustration and increased productivity dramatically when compared to similar applications I'd used at other companies.

    By all means, migrate documentation to cost-effective electronic media. But do that BEFORE eliminating the existing docs!



Add a comment. Registration required because trolls.