The Tortoise Website

The Tortoise Website
Click on image to go to Author website. "THE RACE IS NOT TO THE SWIFT." Eccl. 9:11

Sunday 1 September 2013

Things To Consider When Writing Software Documentation

By Kate McMahon


In today's world we are surrounded by computers which run everything from manufacturing processes to tracking shares on the Stock Market. Each of these applications is likely to be complex enough that the user will need a book to tell them how the software works and what it can do. Writing software documentation might be done by the person who wrote the program, but large applications may require a technical author to produce the final manual.

A technical writer can take the technical world of programmers and designers and translate that into something the average person can understand. They can explain the usage of the application so that a novice user can navigate menus and interfaces required to do their job. Many programmers are unable to achieve this as they write from the viewpoint of a techie rather than the end user.

Many systems these days have very intuitive interfaces which require almost no documentation. Games particularly are designed so that the player learns as they go along. Early levels teach you the basics of the game and hints or tricks are introduced along the way. This technique however cannot be applied for example in running a power station.

Some of the best documentation is written by authors who start from the point of view "How can I do this" and then write instructions which can be followed easily to achieve results from each portion of the app. By following a standard format which take the user from starting the app, through its menu and functions through to what needs to be done in the event of problems, they can produce a comprehensive guide. This guide may then be formatted to a certain specification reflecting the company's style.

It is important for the author to know who the audience for the manual will be. A manual containing a lot of jargon and technical terms if of very little use to an end user with little or no computer knowledge. Conversely one which explained too simply would not suit IT specialists who need to know the inner workings of an application.

All documentation should ideally be clearly laid out, concise and flow logically. The format and size of the finished manual is often determined by the complexity of the application. Some user documentation is extremely lengthy while others might be just a couple of pages of text.

Whatever the size or format, there are some basic facts the user need to know. They need to be able to start the application, understand what it can do and what to do in the event it goes wrong. Diagrams of the menus or screen shots can be a very useful tool and can be easily included in both printed and online documents.

Another method of writing software documentation is to have the programmer, user and writer collaborate. This means the end user can have input, while the programmer knows the information is technically correct. The end result should be a document that everyone can be happy with. A good software manual should be written so that is gives all necessary information about the product while being easy to read and understand.




About the Author:



No comments:

Post a Comment