7 top tips on documentation
This piece was inspired by a disarmingly simple request on the ISO27k Forum.
Tom is implementing an Information Security Management System using the ISO27k standards, in a small company with fewer than 25 employees.
Tom said "I think I need to understand better what should be documented and what not".
Good question, Tom!
- Documenting stuff forces you to concentrate and think carefully about whatever you are writing about. You focus on the topic at hand. It involves and requires a deeper level of analysis than simply doing stuff.
[Hinson tip: preparing documentation is an intellectual process that benefits from experience and expertise. Don't leave it to the office junior, or the person who is generally considered useless and hence has time on their hands. Don't leave it 'til the last minute. Invest in doing it properly and reap the rewards.] - For anything formal (such as policies and procedures) the documentation process generally involves a sequence of activities, several of which get other people involved e.g. in preparing, reviewing, authorizing and using the documentation … so the end products capture and bring together the knowledge of several people. It’s a team effort, a collaboration, a meeting-of-minds. Working together, you are greater than the sum of the parts.
[Hinson tip: assemble a productive team, aligned on common goals and motivated to do a good job. Manage the documentation process and see tip 7.] - The documentation acts as a proxy for the decisions and activities described.
[Hinson tip: you can explain stuff to the auditors using the documents. You can guide and train people using the documents. You can review and update the decisions and activities by reviewing and updating the documents. Within reason, documentation is good ... however ...] - The value of documentation depends on the extent to which the decisions and activities (what people actually do) match the documentation (what they should be doing). This critical control involves aspects such as training, oversight, compliance enforcement and reinforcement, plus the wider business and organizational context – the culture. Do your people read and follow documentation, on the whole, or do they only reluctantly refer to it if there’s a problem, or because the auditors are coming? The way stuff is written and used is extremely important here: it has to be clear and motivational. It needs to be well structured (both the individual items and the overall suite of materials), well designed, well written. It will probably work better if supported by guidelines, training materials and so on.
[Hinson tip: you can even develop metrics to drive these things in a positive direction, if that’s important to you. Ask me how.] - The auditors will object if people don’t do what they are supposed to do, according to the documentation. It's not (just) that auditors are objectionable or sticklers for details. The auditor’s nose is like a bloodhound’s, seeking out these little discrepancies which are legion. Any substantial discrepancies will be reported and may be A Problem for you.
[Hinson tip: counter this by being smart about the way things are written: if people have choices and other options, say so – give them discretion in the documentation. If some things are definite rules and requirements (especially your key controls), be crystal clear about the mandatory bits. For example, reserve “must” and “must not” for absolute mandatory requirements and prohibitions, using “may” or “should” or "ought" or "can" or other such phrasing for the advisory stuff … and have a process to deal with exemptions (authorized non-compliance) and exceptions (unauthorized non-compliance incidents). If the auditors complain about discretionary things not being done as per the documentation, push back by pointing out that they are discretionary for good reason: business comes first. Business people are grown-ups! They are not just empowered, they are expected to do what's best for the organization, within the constraints of the mandatory bits.] - It’s all too easy for docu-philes to write and write [and write] but that can be costly and counterproductive. Keep it simple especially at the start. You can always elaborate later if things are unclear or are not working as planned, or if you discover workable short-cuts and improvements (that's 'maturity'). If you don’t write enough, there is not enough guidance for the people who need it, with gaps and omissions that force them to make stuff up. If you write too much, it won’t be read and it’s expensive to maintain, while inconsistencies and conflicts are more likely. There are information risks either way … which you need to manage. This is something only you can do: without more information about your situation, I can’t advise you on the volume, depth and breadth of your documentation, other than to start small.
[Hinson tip: use diagrams and illustrations, not just words. It takes extra effort and different skills to draw neat process diagrams, for instance, but they make the sequence clearer for users and act as a tl;dr; summary for those who aren’t sure they want to read the whole thing. A picture paints a thousand words, and can be 'a work of art', eh Picasso?] - Designing, building, using and maintaining the documentation suite is itself a process that can be managed, formally designed and documented … but don’t lose the plot. ISO/IEC 27009 is a prime example of when the formalities go a step too far: an internal committee advisory about how to write industry-specific variants of the ISO27k standards unwisely became a published standard, causing problems for the very committee that wrote it! There is some advantage in making the documentation process effective and efficient (especially if you are doing a lot of important documentation, in a big company), but don’t go overboard.
[Hinson tip: take a look at how other policies and procedures in your organization are managed for clues about how to make it work best. Let the process evolve naturally until it works well for you and then capture it in writing only if there is a genuine need for the red tape.]