Video Screencast Help
Symantec to Separate Into Two Focused, Industry-Leading Technology Companies. Learn more.
Inside Symantec Community Blog

Back for More

Created: 27 Apr 2007 • Updated: 02 Mar 2009
Roblee's picture
0 0 Votes
Login to vote
Hi all,
 
I thought I'd answer another question that I've been asked a couple of times.
"Do technical writers actually use the products that they write about?"

I'm sure the reason that folks ask this is because what they're seeing on their screen doesn't match what they're reading in the documentation. So I'll talk about common practices in researching the documents that we write about, and try to give some insight as to why things sometimes go awry.

The amount of actual hands-on use of a product during the research phase of a documentation project usually varies based upon the product's complexity. With most consumer software it's not difficult for a technical writer to get a preview build of the software, interview the developer(s), and then write up the documentation based upon actual use. Source documents from Engineering may provide valuable technical tidbits, but most of the document is the result of the writer using the product and documenting what he or she believes to be the most straightforward way of using the product.

Some products, however, don't lend themselves to that kind of writing process. You simply have to rely heavily on source documents from Engineering. For example, when I was at Intel I helped create reference manuals for embedded microprocessors. These were long (around 800-page) documents with numerous tables of electronic signal descriptions and wave form diagrams. In this case, the great value that the technical writer provided was in helping the engineer organize the technical facts such that they can be readily found and understood by an electrical engineer who was trying to design the microprocessor into a product. While there was a fair amount of editing, there was little original writing involved. After all, there was no choice but to take the engineer at his or her word that when a signal is assert high or low, it will do exactly what is intended. 

Enterprise software has some unique challenges to technical writers who are trying to "get it right." Deployments typically involve a high degree of customization and integration with third-party products. So the functionality that the user sees is probably very different from what the technical writer sees in the test lab. And while we try to set up configurations that we think are representative of a typical customer, there will doubtless be differences from what the writer wrote about and what the customer actually sees. Add to that the fact that a product may be sold in combination with other software packages, and you've got more opportunities for differences.

And then of course, sometimes the writers just get it wrong. It might be the result of a last-minute product change, or a hot-fix that changed functionality, but there are times when the documentation does indeed ship out-of-sync with the product user interface. And that's why it's important to check the Support site for updates to the documentation. Because we release updates to the documentation just like product updates. And yes, it drives us crazy when we get it wrong!