11 Documentation

 

This chapter covers

  • Reasons why documentation is important
  • Different types of documentation
  • How powerful diagrams and drawings can be for communicating
  • Strategies for weaving documentation into your current process

You know this chapter isn’t going to tell you anything you don’t already know—as technologists, documentation is the one area where we fail terribly. It is rare to encounter a company who has adequate documentation—they’re all full of good intentions, but nothing is written down.

Documentation is like test cases: you can never have too much. Though, what is the right level? How do you know whether you have the right amount?

In this chapter, we are going to highlight the areas that need at least a cursory level of documentation and the areas that need more thorough detail, including those that are crucial to the smooth running and continuity of your team. Although this is not an exhaustive list by any stretch, it does serve to get you thinking about

the types of documentation that you should consider to support the systems powering your organization beyond the working lifetime of each member of your team.

Documentation is one of those things that if you keep updated as you go along, it somewhat takes care of itself. If left to languish, however, it quickly becomes a massive undertaking.

Figure 11.1 How do I document?

11.1 Why document?

11.1.1 Audience

11.1.2 Format

11.1.3 Validation

11.2 Documentation types

11.2.1 Meeting notes

11.2.2 Walk-throughs demos

11.2.3 Owner’s manual

11.2.4 Backing up and restoration