The Tortoise Website

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

Monday 11 November 2013

What Goes Into Writing Software Documentation

By Katrina Wheeler


In this age of computers, no company in any part of the planet, whatever its business, can afford to do without them. Being complex in nature, it is a must for computers to provide a user guide to educate users on how to start and use them. Sometimes writing software documentation is done by the programmers but more often it is the responsibility of technical writers.

The kind of writing that is involved is generically known as technical writing. A technical writer who does the job has a good knowledge of software and a proper understanding of the logic behind the software. It could also be a person who may not grasp the complexities of the technology but succeeds in producing accurate and proper technical text.

The job of technical writers is to simplify the complex technical words and phrases of programmers so that non-technical users will not be overwhelmed. Novices should be able to understand exactly how an application is to be started and used, for them to comfortably work with the menus. Programmers have the habit of lapsing into puzzling technical language which leaves users in the dark.

Many regular programs dont need to be explained and are straight forward enough to require minimal documentation. When it comes to the gaming world the game itself instructs the user and as the levels progress the complex functions are explained with tips and tricks. However this would not work when it comes to explaining how a power station runs.

Ideally a technical writer needs to understand a software from the viewpoint of a user who needs to make the most of it and explains the instructions in easy language. There are certain formatting and content standards to be followed, which goes from startup to trouble shooting. The writer will then follow the style and tone desired by the company to ensure that the manual adheres to their image.

It is important for the writer to be aware of who the user will be before writing the documentation. If it is a non-technical user, care has to be taken to avoid technical terms. On the other hand being too simple will prove useless to IT professionals who may require it for support needs.

The whole text of the documentation should have a logical flow and be concise and laid out. The length will vary depending on the level of sophistication of the application or software. Some may be extremely lengthy while some may not exceed a number of pages.

Irrespective of the length and format of the manual, users require some basic facts. They need to know how to start the application, understand its use and solve problems that may occur. It will be helpful to use menu diagrams and screen shots in both the printed and online versions of the documents.

An effective way of writing software documentation would be for the writer to rope in the user along with the programmer. This gives the opportunity to the user to identify ambiguous portions and the programmer checks for technical inaccuracies. The purpose of a software manual is to provide the information in its entirety in a manner that is easily understood.




About the Author:



No comments:

Post a Comment