Software documentation – How much or how little?

Sue Woolley
by Sue Woolley

Tony Self, founder of HyperWrite Consultancy and Training, wrote a thought-provoking article in the February 2009 edition of Southern Communicator entitled, “What if your readers can’t read?”. I read this article with a mixture of interest and trepidation. Interest because I have two teenage daughters, so I know that younger people learn and read in a completely different way to me. Trepidation because, well, are we technical writers all going to be out of a job in the next few years? Will the video-makers and podcasters take over our roles?

I started thinking about how we traditionally document software. Typically we describe all the screens, fields and buttons and then describe job processes, which might include some manual steps as well as system steps. My question is, how much do we need to document? Do we need to describe every last button and field within the software?

There is no “one size fits all” any more—no single documentation/training/knowledge transfer strategy that will suit all users. So, let’s go backwards and look at it from the user’s point of view. What knowledge does a user need in order to learn to use a new computer system effectively?

The four aspects of the user experience

Software designers need to consider the following four aspects of the way people approach their use of new software and resolve any problems they encounter.

  1. Users need and expect that the software is easy-to-use and intuitive.
  2. Users have different learning styles, so there needs to be a range of training options available. Users need to have a choice about how they learn through options such as instructor-led sessions, online self-paced learning and videos.
  3. If the user has a problem when they are using the software they need to be able to easily find the exact piece of information they need.
  4. If all else fails, the user will ring the support desk for help.

We as technical communicators have a role to play in each of the four user-experience stages.

User interface

The user interface to the software needs to be easy-to-use and intuitive. Options should not be hidden away and the interface needs to be consistent throughout, clear and effective, and allow users to perform their tasks efficiently.

Technical communicators have an important role to play in designing and testing the user interface and providing feedback to developers. One of our primary skills is putting ourselves in the shoes of a user and looking at the software from their point of view. We have a very important role to play as the user advocate to keep developers focused on keeping the user interface easy-to-use and logical as opposed to just concentrating on the technical aspects of delivering a solution.


Many small software companies rely on one or two experts to give face-to-face training. They often don’t have any training materials to give to participants, but get away with this mode of teaching because of their encyclopaedic knowledge of the product.

This can put a strain on the experts as a company starts to grow, with one or two key people trying to do everything from sales and implementation to training and support. Many small software companies also struggle to go to the next level. The pressure can be relieved by investing some time and money in documentation and training materials.

If the company has invested in a single-sourced documentation solution, producing training materials for instructor-led sessions can be a relatively painless experience. Single-sourcing means that content from the product documentation can be re-used in the training materials. Some product documentation may also be able to be re-used to produce online self-paced training materials, or used as scripts for videos.


Very few people these days will sit down and read a manual for a new software product. The expectation is that we can install software and start to use it straight away. The younger generation in particular is so comfortable with new technology that they dive in and expect it all to work. They explore fearlessly, and are able to master complex hardware and software concepts effortlessly.

If a user has a problem when they are using the software then they will generally either ask a colleague for help or resort to trying to find the answer in the documentation. Typically they will “dip into” either a manual or the online help and at this point. If they can’t easily find the exact piece of information they need, they will be frustrated with the software.

Documentation is, therefore, rapidly becoming a backup for deficiencies in the user interface and user training rather than a complete solution in itself.

Help desk support

If a user has a problem and all else fails, they will ring the support team. The members of the support team need to have been trained, and have a knowledgebase, including comprehensive documentation, available to them to be able to solve user problems quickly and effectively. Again, the technical communicator should have a major role to play here, making sure that all the common problems and solutions are documented and that the support documentation and knowledgebase is easily searchable.

A technical communicator has the potential to save a company a large amount of money on support costs.

How comprehensive should our documentation be?

Should we give up writing documentation and put all our efforts into an intuitive user interface? An intuitive user interface is vital, but is only one part of the whole picture. An intuitive user interface can help reduce the detail in the documentation. For example, if screen names, tab names and field names are all obvious, if compulsory fields are flagged and tooltips are used, then we can get away with not documenting all these in detail.

The key is that the training, documentation and support desk need to be able to quickly answer any question the user has when using the software. We need to continually be asking ourselves, “What does the user need to know?” We need to research and document all the “How do I...?” questions and extensively document processes that are only used irregularly, for example end of year financial processing.

So the documentation does need to be comprehensive, but it also needs to be structured so that:

  • Users can find the exact piece of information they need at the exact time that they need it. You must provide multiple access methods such as a table of contents, index and full text search facility for online help to cater for the different needs of users.
  • There is a comprehensive set of “How to...” procedures.
  • The documentation is topic-based. This will help users to find a small item of information without having to read lots of unnecessary material. Each topic should have a title that clearly indicates its content.
  • The documentation is single-sourced. This allows you to easily produce the same content in different forms for different audiences. For example in training materials, user manuals, help desk support documentation and web content. The traditional way of writing user documentation is definitely changing. I think a lot more thought needs to go into the planning stage to ensure that all the pertinent information is captured in a way that it can be easily found.

Do we need online help?

I asked my daughters about how they would go about learning a new software package. Both indicated that they would try out all the different menus and options until they found out how to do what they wanted. If they couldn’t work out how to do something themselves fairly quickly, they would resort to looking in the online help.

I asked if they would view videos if they were available, and was met with a resounding “No!”. Videos are sequential in nature, so you have to be prepared to invest a certain amount of time watching the whole thing when you may only want a small piece of important information. Most people are time-poor, or in the case of the younger generations, impatient.

I believe that instructional videos can play an important part in the training stage for some types of users, but won’t replace online help for documenting a product.


I don’t think that technical communicators are going to be out of a job in the software development industry in the foreseeable future. But, we need to be concentrating on how to provide “moment of need” information, which means that we have to find a way to insert ourselves into the software development life cycle rather than only being seen as part of the end of the process.

One way to do this is to present a business case to management. The only compelling argument will be based on dollars, so you will have to be resourceful and think about how your skills and experience can save the business money.

I challenge you to start thinking about how you can persuade your management to make greater user of your skills and make you an integral part of the software development process.

Back to blog home.