Thoughts on Documentation
Written policies and procedures are not just the foundation of IT organizations. Documented policies and procedures are the bones of information technology-driven organizations. Everything else is ephemeral--a temporary engagement.
The ISO/IEC 27001:2022 standard is a good template to use as a starting point when creating policies and procedures for an IT-driven organization. ISO27001 relies on documentation. If it isn’t written down, it does not exist.
Ask for too much documentation and you might not get any.
💡
Some definitions:
Policies: Documents that define requirements or rules. These are high-level guidelines. Example: Incremental backups must be performed daily, with total backups completed each week.
Procedures: Describe how a requirement or rule will be met. Example: Incremental backups are performed with a cronjob, which is running on server backups00…
Policies: Documents that define requirements or rules. These are high-level guidelines. Example: Incremental backups must be performed daily, with total backups completed each week.
Procedures: Describe how a requirement or rule will be met. Example: Incremental backups are performed with a cronjob, which is running on server backups00…
Benefits of Documentation
- Documentation reduces the likelihood of a single point of failure.
- Documentation aids reproducibility.
- Documentation saves time.
- Frees staff brainpower, and creativity, for new and more difficult challenges.
- Makes systems easier to understand, easier to use, and easier to modify.
Best Practices
- Standardize on short, lightweight documents.
- Write many one-page documents, each covering a single topic.
- Start with the big picture. Then, break it down into pieces that contain more contextual information. (If more detail is required, link to one or more additional one page documents.)
- Set the expectation that documentation is concise, relevant, and unpolished. The important thing is to get the information down.
- A standard structure helps avoid blank-page anxiety.
- Integrate documentation into processes.
- Do not create information redundancies. Information should only be manually updated in one location or document. Everything else referencing that information should use links to only one source of information for any particular topic, policy or procedure.
