Agreed you built the coolest product in town that allows your customers to integrate that PeopleSoft Financials accounting system with your Siebel CRM. But how on earth are your users ever going to use the damn product until you have user manuals telling them how?
What follows is a condensed description of the software documentation process followed in most product companies around the world.
Understanding the Documentation ProcessThe user documentation process ensures that you have a set of standardized support documents to assist your customers use the product. A product not supported by good documentation is a dead product. Therefore, reliable product documentation is not only crucial for your customers, but it also decides the fate of your product in a competitive market.
This article helps you understand the documentation process followed in most product companies across the globe. Although, companies might adopt different flavors of the documentation process, the basic flow remains the same.
Determining Product Readiness
At this stage, make a decision to follow approach 1 or 2.
You might want to choose approach 1 if your product is QA tested and ready to go to the market. Identify a writer and hook the writer up with a Subject Matter Expert (SME). Since you will be at the end of your product development cycle, the writer will have a ready product to play with and learn the product on the job, reducing the learning curve.
If you are at the start of your product development cycle, you might want to choose approach 2. Large product companies identify and train a team of technical writers at the start of the product development cycle. Writers are invited to crucial design meetings and encouraged to review and provide feedback on design documents. In such cases, writers start to work on documentation at the same time when developers start coding the application. Source documents, such as functional and technical design docs form the major source of information for the writers in this model. Writers also interview SME(s) to know about the product.
Reviewing Market Requirement Documents (MRD)
Most companies collect market requirement documents to give a direction to their products. MRDs are a reliable source to understand the philosophy behind the products. Writers can use these documents to create scenarios and highlight product relevance to users.
MRDs also provide the framework for functional and design documents down the stream.
Analyzing Target Audience
The writer along with the SME does a target audience analysis and establishes the profile of the user. MRDs are a great source to understand target audience.
Users of a system are not all the same. The writer must structure the doc to cater for different user tasks and different levels of expertise and experience. It is particularly important to distinguish between end-users and system administrators:
End-users use the software to assist with some task. This may be flying an aircraft, managing insurance policies, writing a book, etc. They want to know how the software can help them. They are not interested in computer or administration details.
System administrators are responsible for managing the software used by end-users. This may involve acting as an operator if the system is a large mainframe system, as a network manager is the system involves a network of workstations or as a technical guru who fixes end-users software problems and who liaises between users and the software supplier.
Determining Documentation Types
Depending on your audience, you can choose to have several types of documentation. If your audience largely consists of novice users with limited experience with a computer, you might want to create an introductory manual, such a Getting Started with the System guide. Documentation deliverables can include, but not limited to:
· User Guide
· Implementation Guide
· API Guide
· Online Help
Creating/Writing the Documents
After you have decided on your documents, set up a team or engage a single writer depending on the volume of work. Best practice at this stage includes drawing a schedule and managing that schedule to ensure that your documents are of high quality, technically accurate, and on time.
There are several documentation tools. Examples include:
· MS Word
· FrameMaker
· AuthorIT
· Epic Editor
· RoboHelp (for Online Help)
If your documents include large number of pages, use Frame Maker 8.0, the most recent offer from Adobe. If you need XML output, use Epic editor. If you want to tear your hair out, use MS Word.
Reviewing Documents
Set up a process to ensure all documents pass through language and content edit. Ideally, language edits are done by language editors based on in-house style and standards guide or widely recognized style guides, such as Strunk, MS Manual of Style, and the Chicago Manual of Style.
Send all documents for technical edit to ensure that the content is correct and syncs with the product functionality. A good user document is one that is referred to as the source of truth by everyone in the company.
Testing Documents
It is a good practice to QA test documents, such as Installation guides and Quick Reference guides. This way, you get to squash the bugs even before they are reported.
Publishing Documents
Once you are done testing and finalizing your document, you need to publish the documents for your users to access. The most common way to publish is to create PDF files and burn it along with the product CD or upload the PDF files on the web.
So there you go! I have outlined a basic documentation process. There are many more components to the process that need attention depending on the size and commitment of your company towards documentation.
