I believe that 1.0 docs should be as sparse as possible and then expanded very, very quickly. Even when a software is brand new there have always been at least a few users. For this to work the tech writer has to be closely integrated with tech support, not just talking to them on a weekly basis, but literally cranking out docs as the questions come in.

For this to be possible the docs need to be web based obviously. There are some people that still need printed docs but that number is shrinking rapidly.

The main problem I see is that what I describe isn’t possible in larger organizations because support and tech pubs are in separate silos. Smaller companies have much smaller teams and are usually closer to their customers.

As far as support people writing bad docs, that can be true, but I really believe that a product like ScreenSteps can mitigate most of those issues. When most of your docs are pictures the clarity is in the picture. If the words are a little muddled it isn’t the end of the world. In an ideal world , the support agent would create the initial doc to help a customer immediately. It would get added to a central documentation repository and a tech writer would come back and edit and refine it to polish it up for future users.

Like you say, this isn’t possible in many organizations but I do believe that it is the most effective way to support customers and scale a new product. Thanks again for the comments.

In many cases, we technical writers plead for contact with customers but are told that’s not allowed. I do interrogate support folks for a list of the most common things users ask about.

However, one thing you don’t mention is where does the release 1.0 documentation come from? For a brand new product that’s never been given or sold to real customers, someone still needs to create the documentation. That’s where experience in technical writing makes a huge difference.

Another thing you don’t mention is that even though support folks are great and I love them, they don’t (for the most part) know how to write well and they don’t (again, for the most part) know how to create a document that doesn’t look like a ransom note.

Since they feel the pain they have the most incentive to get it right. Also, since they are on the “front lines” they have the quickest and most accurate knowledge as to what is really needed.

You can establish a process where tech support suggests a topic to be documented, then the tech writer authors it, and it gets approved and then gets published a week or a month later. Or you can just let the tech support person add to the documentation.

Maybe it’s not that tech support needs to take over the tech writer’s job but instead that tech writers need to be doing the job of tech support.

However, I have to take issue with the sweeping generalisations about tech authors having little or no interaction with the help text audience, or that their experience is usually limited to writing requirements documents and little else.

One of the first things I learned when I became a tech author in 1998 was the importance of writing for the audience, whether that’s an end user or a colleague. A skilled tech author can translate for different audiences, whether they’re internal teams or stakeholders, third parties, or customers. Furthermore, we aren’t all isolated from our audiences. There are an increasing number of ways to engage with external readers, and not all help documentation is written for people outside the environment it is generated in.

I fully accept that some tech authors or Tech Pubs departments would probably benefit from more engagement with their audience, but I can’t believe the only solution is to hand over a key skill/role to another job title.

An interesting article that’s definitely got my neurons firing. Thank you, and I’ll be back to read more.

Are you using ScreenSteps? We are just using the standard ScreenSteps PDF template with our logo added to the top. If you are trying to get started creating your manual I would suggest reading this article:

5 Steps to Improving Your Software Documentation

Or did I misunderstand your question?