“Effective” – The Must Behind Software Documentation August 6, 2008
Posted by Amal in Editing, Software Documentation, Technical Writing Basics.Tags: Design Documents, Software Documentation, Style, technical writing
1 comment so far
In most mediocre IT firms the key responsibility of software documentation remains in hand of developers. Technical Design Documents, User manuals, Help References are all involved as a part of the software development phase. In bigger houses however, the idea is changing. Technical Documentation and information development is a process throughout. So where do we start when we have the responsibility? Let us check out -
The main reasons for user documentation are as follows
* Helping users with the developed software
* Reducing support costs
* Powerful business and marketing tool
* Improving a software firms reputation and brand identity
* Helping with QA, Process and Management with technical stuffs explained.
Before documentation we should identify the reason behind that particular process. For example a document with marketing aspect would be different than that targeting the QA team who should test the software.
Analyze your audience
“It’s very good looking”, “It’s very attractive” are not what a Technical Communicator needs to listen. The only phrase that should matter for each document is “It’s helpful”. Yes, you should style it, publish it with enough details and attention, but never forget the target audience.
The easiest way is to analyze users by designation or job responsibilities. Whether the documentation is for:
1. Users of software
2. Quality Testing guys
3. Administrative professionals
4. System Professionals
You would know by the roles who is a novice and who is a techie. Who needs validations, database structures and who needs less than that.
By analyzing audiences you will provide:
1. Information as needed
2. Easy, helpful and Handy document
Analyze Tasks
How often should you write? Whenever. Make it your hobby.
How often then should you communicate? As much as you breathe, make it your need.
You should analyze tasks, tasks performed by members of QA team, System team, Project Managers, coordinators, and Data Entry Operators. By communicating you will know where they lack, what they expect, how can they be helped with information. Communication makes your job easier; in process you make their job easier. That is what the main responsibility of a Technical Communicator is.
Structure, Styles and Information
How a Technical Communicator use styles, structures and document the information depends on what each document should address to. All documents should answer particular questions. Here is an explanation, On a very macro level:
| Document drafted for | Should answer to the Question |
| Client (Business Documents) | Why should your service be better, how good is your understanding about the requirement, how capable are you to provide solutions for the requirement. |
| QA, Analysts (Design Documents) | Validations, How Should the interface works. What should be the ideal conditions for software to work? |
| Developers (Logical / Technical Documents) | What should we keep in mind while developing? What was planned? How was it planned? Why was it planned? |
| Users (End user documents and help manuals) | How does the system work? How should a particular thing happen through software? |
| Novice Users (documents for primary end users and internal novice users who use the software for example, data entry operators) | How should the software help? How is it easier to use? How should a particular task be achieved in the simplest manner? |
Software Documentation is as fun as you can make it, but never make your documentation funny. Make them effective.
