So where does the documentation fit in with my project plan?
Traditionally, the documentation comes in towards the end of the testing stage of your project. The software is more or less stable and you're close to launch. Having seen the stages involved in the documentation, you may be thinking that it's a lot to cram into this stage. You'd be right! This is why many project managers see documentation as that necessary nuisance that takes up valuable manpower to create and review just when deadlines are looming.
So it is also vital to consider the effects of the documentation at the initial planning stage.
In this first stage of your project, your planning will include such things as:
§ Timescales and resources
§ Roles and responsibilities
Timescales and Resources
When thinking about timescales, don't forget the time required for the documentation! It may seem obvious, but effective documentation takes time to develop. As seen in the typical documentation project plan above, the elapsed time can be much longer than just the writing time due to the review process.
Depending on the scale and complexity of your software, you may have to consider splitting the documentation between different authors. Authors working in parallel can speed up the process, but be warned – depending on the tool(s) used to create the documentation together with the associated workflow this may not be possible. In addition, there is the extra issue of keeping the documentation consistent across the authoring team.
As well as providing the writing resources, it is just as important to provide adequate resources for the reviewing and a documentation project manager to coordinate writers and reviewers. All this must be factored into the cost.
With so much to do in the testing stage of your project plan, the inclusion of the documentation at this stage and the drain on expert staff for reviewing presents a real project risk if not properly planned and resourced.
Roles and Responsibilities
Who should write the documentation?
If your organisation has a specialist documentation department then your solution is simple.
So what are your options if this is not the case?
The programmers themselves
Seems logical. They certainly know the product inside out. But beware. The programmers are experts in programming – not necessarily in communicating! They may well assume a level of knowledge that the end-user does not have. Not only that but their enthusiasm for their creation often gives them an understandable tendency to explain every last technical feature in detail – focussing on product functionality rather than answering users' questions.
A contracted technical author
This is often a good solution, though it very much depends on the rest of your project plan. In the build stage of your project plan, you may be setting aside long stretches of time on the coding of the software between tests. Unless there are other projects to work on, a technical author can be left idle and compromise your budget.
Outsourcing
Contracting an external organisation to project manage and develop your documentation means that you will only get charged for the days spent managing and writing. This solves the problem of idle time, but does have a couple of disadvantages. One is that the author spends most of the actual writing time off-site so direct communication may be more difficult. The other disadvantage is that it may not be possible to guarantee that one particular author will be available if timetables and deadlines change.
Who should review my documentation?
You may want or need more than one reviewer. As already mentioned above, all the documentation at every stage must be reviewed by at least one expert in the software. This ensures fitness for purpose and technical accuracy. In addition, it is often useful to get other relevant people to review parts of the documentation. One example is if you have access to some helpful end users. Their comments can be very valuable. Another example is if there is to be a training programme for the software. The training staff can provide useful feedback.
Who should manage my documentation?
As stated previously, the documentation project manager is necessary to co-ordinate the writing and the reviewing process. Unless your programmers are writing your documentation, many questions will arise on the author's part about the details of how the software is to be used. So part of the project manager's role includes co-ordinating these questions and their answers between the author and the programmers.
If you are outsourcing, the external company manages the delivery of the drafts, the receipt of review points and the author's questions for the programmers. However, there should still be a person named as the documentation project manager in your organisation to provide a single point of contact for the external document project manager. Without this role, review points get fed to the external company in dribs and drabs and sometimes contradict one another.
