Many Project Managers and Subject Matter Experts fail to understand the challenges posed by documentation projects. To lead such a project, you need to know what is important and how you will achieve the goal. What preparations should you make to ensure you complete the project within budget?
Here follows the best advice on the documentation projects, before, during and after.
Until the information and gathering phase begins, do not even consider a guess about how long it will take to complete the documentation.
As the list of titles grows, Management may need to consider extending the budget to finance the project. Abandoning the documentation when it is ‘Nearly there’ will be waste of money, time and resources.
Decide the output format
When the Technical Writer has written the documents, consider which of the following formats will suit the company’s requirements.
MS Word stored in a Document Management System
PDF stored in a Document Management System
*.CHM files created by using such application as RoboHelp
Wiki formats: A Wiki provides the user community with the opportunity to provide documentation feedback
Future Review Requirements
Do not overlook the future requirements of any project. All documentation is an ongoing project. Establish a workflow between the IT teams/Process teams and the documentation department to update documentation.
Update the documentation when:
the IT teams upgrade or modify the Server/Application/technology
document all changes, using a change management process to prevent any repeat the configuration
align the documentation and the project
Revise the Project
On completion of the project Use the documentation to:
reflect the changes and updates
test to ensure instructions are clear, concise and correct
Avoid considerable time, frustration, and future expense by correctly applying documentation strategies to:
. . . ensure that users can follow the instructions
. . . provide a historical record of the changes made during the project
Why is it that companies view the cost of Technical and Process documentation as an unnecessary expenditure rather than viewing documentation as a centre of knowledge? Management seems to have a blind spot with documentation and conveniently forgets the role of documentation.
When redundancies beckon, I know how quickly management will sacrifice the technical documentation department. When management seeks layoffs, the technical author(s) will be amongst the first out the door. Months later a member of staff points out that the documentation is out of date and follows up by asking: do we have anything up to date we can use?
In sacking the technical documentation team, no one assumed responsibility. Keeping it up to date is left to those least inclined to keep it up to date. They are the people who would benefit most from its upkeep.
Within a software environment, we easily forget that as the developers progress their software application, it also becomes more complex. Failing to supply up-to-date documentation means customers can overlook many of the improvements and advanced features. We could say the same of any IT department. As the network grows, there are more questions and fewer answers. No one has a good overall knowledge of the network because of the lack of documentation.
Where does that leave technical writers?
However, you refer to us, be it technical authors, communicators, documentation staff or as the font of all knowledge. Never doubt our experience, our people skills, our ability to write clear instructions. We can explain complex technical terms in easy-to-read formats. Who else will put up with blank stares, sarcastic comments and listen to comments such as “whaddya want now?’ to get what your company needs; usable documentation.
Remember, it is not about the cost of hiring a technical author. It is about our value to your organisation. Our documentation will keep your staff informed and up to date. There is a point to keeping your processes up to date as your working environment changes. It is also about keeping that software guide up to date enabling your customers to use your product more efficiently and know they invested in a superb product.
Finally, don’t forget that a technical author will not only you save money now but also at a later date and will keep on saving you money, therefore, over the long term justifying their value to your business.
When you start the process of Hiring a Technical Writer, my advice is this: do not cut corners when sourcing a budget:
Check the daily rates/hourly rates. Do not expect an experienced technical writer if the daily rate is derisory.
If your rate is low, you will attract Technical Writers with less experience whereby the result could be a disjointed document with no formatting and poor English
A good TW who charges a higher rate may save you money by taking less time to do the job.
Your Technical Writer in the flesh
Many TWs will have worked in a variety of environments. In due course, we gain knowledge that could provide a solution to other long-running problems. Hence why managers should never underestimate TWs.
What will you need?
Before you actively engage the TW on your site, do you have all equipment ready:
One of the most common problems is no laptop on the day they start
That their profiles to log in to the network are set up
If they are reviewing existing documentation make sure it is available
When you start explaining the work to a TW in company-specific jargon, do not assume they understand you. There is a good chance that the TW during an interview may mention that what one company knows as “XYZ” may not be the same as yours.
What should you do?
Be certain the SMEs or others with whom the TW will engage are aware of the appointment and know the goals of the project
If you are the primary contact do not disappear without the TW knowing where you are or who is second in command
Do not assume the TW is less than proactive if you cannot see them writing down a list of questions and talking to the appropriate people. If they are reviewing existing documentation, they may need a few days to understand the content before they start acting pro-actively
If after settling on a start date
If a problem arises let the TW know in advance because:
You may need to change the start date or find another job for the TW to assess.
Delays will only diminish your budget if the TW is on-site with nothing to do.
If the problems are likely to be ongoing be honest and let the TW know – do not consistently change the start dates because it is not very professional and TWs do talk to fellow TWs.
Be consistent with the project, its objectives, and deadlines
Do not change the parameters of the project by allowing project scope creep.
Communicate with the TW as S/he may not have the time to stay beyond the current time allotted for the project.
Make contingencies if you need to extend the contract
What will the Technical Writer do for you?
Supply a project plan. Do not expect one within a matter days. if they own a generic copy, they can adapt it for the project; else create one from scratch.
The project plan should include a documentation schedule, including milestones and how progress can be measured.
On longer projects, TWs will complete a weekly project management report, which will outline problems, issues, bottlenecks, etc.
If the contract states that travel abroad or within the UK is necessary, make sure they are available to go.
Foreign travel as part of the contract
Some companies expect contractors to pay their expenses up front on foreign trips.
Might I suggest that they:
Can afford to do so without getting into debt.
Know the procedure to claim their expenses
Be clear on when the payment will be paid
I once submitted expenses, which, due to a misunderstanding took three months to process.
So, after the initial shock of discovering what happens when you have no technical documentation, what can you achieve now that you have technical documentation?
1: Have you employed/contracted a Technical Author . . . Great!! If not what’s holding you back . . . remember we bring value
2: If you cannot see your technical author at their desk you’ll no doubt find him/her performing Vulcan mind melds and extracting the necessary technical information from the heads of your development/infrastructure staff (if it looks painful don’t worry, the job is mandatory!)
3: Start a discussion about what you need and I’m certain your technical author will only be too happy to help?
4: Once you have technical documentation there is no more guesswork as you have plenty of reliable data against which to measure the progress of future projects
5: You can also employ a project manager who can plan ahead because you know everyone who needs it!
6: Documentation is no longer a problem and what you require is what you will get . . . Congratulations!
It is not unusual to find companies still use Shared Drives to store their documentation. As many Technical Writers will point out, the problem with shared drives is that they are neither secure nor searchable.
What is the problem with shared drives?
The folder structure has too many levels meaning documents are difficult to find
There are information gaps as users keep copies of documentation locally and not on the shared drive
There is no formal ownership of the documents
The title and subject of the document does not accurately reflect the content
Document versioning is not used meaning the latest version is . . . Where?
There are many copies of the same document
The failure to maintain a workable Archiving policy means many documents with the same title contain unchecked updates
There is no historical tracking of documents to keep integrity of the content
Searching for documents on a shared drive will raise many unrelated results
Using a non configured Document Management System (DMS)
It would seem ironic that companies do spend a large amount of budget on installing a DMS such as SharePoint but fail to task an experienced employee to set it up correctly. So what happens when the DMS is left to grow without the correct administration?
Failure to lock down user privileges means it becomes a free for all with no proper administration
Check In, Check Out, Document Versioning and Security are not configured meaning user’s drop off documents where they see fit
There is no historical tracking of documents to keep integrity
Users create folders without proper titles and lose their document
Backup of the DMS is irregular
If you want to manage your documentation in a way in which it cannot become a free for all you need to consider a form of document control and establish a policy and a set of rules to keep your documentation in check.
Technical and Process Documentation is an asset, and your staff should treat it as such. Look after it, and it will look after your business.