There comes a time when every software development manager has to find an answer to the question 'who's going to write the user's guide?' In major corporations, where there is a well-established technical publications department, the responsibility for the user's guide would have been allocated early on, as soon as the design specifications were approved for development.
However in many small and medium-sized enterprises the user's guide question often becomes a problem that everyone tries to ignore.
In the last dozen years as a technical writer in the software industry I have heard a whole range of excuses as to why the user's guide question is not important. None of the arguments put forward stand up to close scrutiny.
We don't need a user's guide as our GUI is so intuitive
Many software developers truly believe that their product, and particularly their graphical user interface (GUI), is straightforward and easy to use. They assure me that the GUI adheres completely to all the industry standards for the operating system and that no one could have a problem with it.
However it is often the case that something obvious to a developer is less obvious to the user. GUI metaphors that are second nature to an experienced developer may be totally strange for a user for whom this may be one of the first applications they ever use.
Even an experienced user can have problems when a new version differs significantly from an older version of the same product, or when a newly-launched application differs from a comparable application from a rival vendor. Users need some reference information to help them, and a user's guide is the natural place for them to look for it.
It's been through QA testing so it must be easy to understand
In my experience QA testing tends to concentrate on whether code executes properly and without errors. Manual or automated testing works from a script that specifies, for example, that when the user clicks button A the application displays dialog B. As long as this happens the software passes the test and is declared bug-free.
QA testing doesn't look at whether a user would understand that in order to display dialog B they needed to click button A, nor whether the user would understand the importance of completing the fields in dialog A in the first place. In the absence of usability testing (even rarer, unfortunately, than user documentation) a well-written user's guide can explain what the user can see on the screen, and map the screen buttons and dialogs to the user's tasks.
All our software engineers know how to write
I don't doubt that many software engineers do know how to write about the applications they have developed. After all they are clearly the experts when it comes to the code they have written. It is less likely that the software developers are experts when it comes to understanding the user's expectations from the software product, and therefore they are unlikely to write what the user wants to read.
The developer's view of software is, naturally, code-centric, while users see a software product as just another tool, like a calculator, or a pen and paper.The user needs to get their job done quickly and efficiently, and will use the best tools they can find. They are not interested in the internal logic of the code behind the application nor in the table structure of the underlying database, any more than DIY enthusiasts are interested in exactly how their hammers are made.
We leave that sort of thing to our marketing department
Marketing departments are concerned with getting potential customers to part with their money. Everything they write is written with that in mind. They don't need to explain exactly how a product works. If they are writing about a technical product, they do make use of technical information.
They are likely to select the most interesting and attractive snippets of technical information, and whatever jargon they feel is most likely to make the product seem new and innovative. Once a customer has bought and paid for your product, the marketing department is no longer interested in them. Quite rightly, they are busy going after the next customer.
Even if the technical marketing literature does describe your product's features well, there is no guarantee that the people who are going to use the products even saw the marketing brochures. It is very likely that they, the users, aren't the people who are authorized to make purchasing decisions.
Our users are sophisticated and don't need instructions
When you are selling to early adopters it is possible that your users are technophiles like you. That might sound like good news, but it might also mean that if they can't understand how something works they will try and 'look under the hood' themselves, perhaps even trying to reverse engineer your code. If the answers were in your user's guide they wouldn’t bother with 'fiddling around'.
In any case commercial viability requires that you sell beyond this initial market segment and into a more general one, where by definition the average user is going to be less sophisticated. These are the people for whom a well-written user's guide can be really valuable.
If our customers have a problem they can phone the helpdesk
Do you really want your helpdesk to be clogged with calls about simple and straightforward operations? That makes your response times look very poor. If you are in a company that generates revenue from customer support lines, do you think that your customers will be happy wasting their precious support minutes asking about file formats, directory paths or any other basic information they could have read for themselves?
Your support staff themselves would benefit from having a clear and comprehensive User's Guide in front of them, and from knowing that their customers had copies of the Guide as well. The customer support log would then be able to show which topics were not yet adequately covered in the user's guide, so that the next edition would be even better.
We'd love to have a user's guide but we just don't have a budget
It is difficult for companies, particularly start-ups and smaller enterprises, to have the same level of investment in peripheral activities as major corporations. It is particularly difficult to fund activities that appear to create no value for the company. But a good User's Guide is really an essential part of a software product, just as much as the GUI, the installation package or the code itself.
Printing costs can be high, but a User's Guide can just as easily be delivered as a PDF file or even better, as an online help file. The minimum cost of developing a User's Guide is the cost of the technical writer, who could easily be a contractor if your company is concerned about headcount.
The costs involved in providing a User's Guide need to be set against the benefits. Your products become easier to learn and to use, creating the kind of grass-roots customer loyalty that is difficult to buy. Frivolous calls to customer support are reduced, giving your staff adequate time to deal quickly with more significant problems.
Your company's reputation is also enhanced when you provide good user documentation, leading to better market recognition and enhanced sales. And hiring a technical writer means that you ensure that your programming staff can devote all their time to what they do best - writing code.
