In the IT companies, there are different types of documentation created in the course of the product/project development. These documents are written by different authors based on their area of expertise: product manager creates the requirements document, QA creates test plan/test cases, architect comes out with design document, engineers come out with functional specification, and technical writers create the customer-facing documentation such as manuals, SOPs, white papers, etc. Below are some standard forms of documentation frequently generated during a product’s lifecycle. Under each type of document are some fundamental elements.
Requirement Documents (created at the initiation of a project, written by product manager):
This describes whom a product will serve and what it will do. It includes listing the users and how they would use the product, and for what purpose (also called use cases); a definition of the overall system architecture and development methods; a description of how the development team will do its work (what will be developed first, what might be added as additional features if there is time/money available); a schedule showing how long the development process will take; a concept of operations for using the product; a lists of participants, roles, and responsibilities; and eventually detailed descriptions of the data to be acquired and how it will be manipulated.
The audience is often information technology managers, who want to ensure that a development team knows what it’s doing, that resources are being used wisely, and that the work is proceeding according to plan.
- Date and authorization
- Project scope/overview
- Task proposal
- Proposal validation
- Business goals
- Time and expenses
- Resources and support.
Functional Specification Documents (created for Developers and written by Developers):
This communicates how things should be designed or built. Unlike requirements definition, which can be done without a lot of formal training in an engineering discipline, specification/design documentation usually requires hands-on experience with the tools, hardware, processes, and terminology needed to do the job.
These documents are often written by “engineers”.
- Technical details of the product
- Detailed tasks
- Database design and schema location
- Client needs
- Program functionality
- System platforms
- User Interface
- Error messages.
User /Operations /Training Documents (created for guidance and instruction, written by Technical Writer)
This is the type of documentation most people are familiar with. It’s the PDF or online help module that people refer to when someone is looking for information. It’s a step-by-step process document that walks a user through the process of operating or employing a piece of software or an engineering product. User documentation often employs a dual-form organization, meaning it’s broken out by function, but is chronological when describing individual functions. It includes possible cautions and warning, which appear before a step is taken so the user is aware of a problem prior to taking any action. It establishes technical nomenclature and provides a glossary of those ever-present acronyms. It also ties the product’s functions with work functions.
To write user documentation, you have to become familiar with the user’s actual work processes: what their primary tasks/outputs are; how they normally encounter the product; how often they are likely to use it; how dangerous errors are if they occur and how they can be addressed; how do they handle exceptions or unusual situations; and what personal safety equipment (if any) they are likely to require to handle the product. In the space world, a payload user guide would tell a prospective payload manager about how they would go about delivering their payload to the rocket manufacturer, what sorts of interfaces they are likely to need, and what types of environments their payload is likely to experience during launch, and so forth.
User documentation is the best example of “translating technical jargon into English” and is often the most challenging and people-intensive technical writing you might do, as you must be able to absorb what the engineers are doing; advocate for the user if the product is creating problems, confusion, or dangers; exercise diplomacy when challenges arise between the designers/developers and the end users; write user test cases that make sense for the users’ work environment; operate as a guinea pig (test subject) for the user test cases; and keep the documentation updated as product/version upgrades arise.
- Guide description
- Product description
- Installation and/or log-on procedures
- Program functionality
- Required information
- Prompts and error messages
- Trouble-shooting section
- Reference sheet.
Reference/Cheat Sheets (created as a quick look-up) contain:
- Brief program overview
- Brief explanation of each functionality
- Quick ways to accomplish a task
- Brief trouble-shooting section
- Index and cross-reference sheets.
Quality Assurance/ Test Plan Documents (created for testing, written by QA) contain:
- Program description and client needs
- System requirements
- Program accessibility
- Tasks and scenarios
- Regression testing
- Problems and resolution.
SOP (Standard Operating Procedures) Documents (created for routine tasks, written by Technical Writers) contain:
- People involved/affected
- Revision instructions
Visit www.ThomasEcafe.com, or call +65 82086393, or email: info@ThomasEcafe.com to discuss your writing and editing requirements.