Bootstrapping and Rooting Documentation: Part 1

Bootstrapping and rooting are two concepts often associated with computing, but not the documentation of computing environments. Sometimes concepts such as these are called design patterns and I would like to try and introduce a new pattern called Documentation Bootstrapping. I think this is a critical pattern for the creation of any successful and useful documentation.

Often the goal of documentation is to allow the architect to exit from the production life cycle of a project, program, or system. As such, he or she must put enough information in the documentation to allow others to use the program or system without the architect’s presence. When the documentation is complete the architect moves on to the next project and the documentation continues to grow organically with the program, project or system. This is a normal course of action in software development and generally works. The body of knowledge that is left behind is generally canonical, take the Apache web server as an example.

On the operations side, this is usually not the case. Documentation grows organically with scripts, software installations, hardware installations, network growth, etc. In this progression, the documentation is never rooted to a central authority and it is commonly difficult or impossible to tie all of the documentation together in a way that is meaningful and useful. This means that there is never canonization of the documentation and as an architect that implemented the software installation or network change moves on to the next project, his or her documentation is often lost.

This leaves us with documentation that is hard to expand upon and often treated like an archaeological find. We will comb the documentation and code for clues as to what the architect was thinking when he or she implemented the system, but it will not provide enough information to be genuinely useful. As this generation of architecture expands the system our progeny are left with the same problem.

There is a solution, I will call it Documentation Bootstrapping and I gleaned it from the Gentoo project’s documentation. Here is why I think it works.

First, the entry point to the system is through the documentation. You cannot start using Gentoo without first starting with the documentation. This is different than Fedora or Ubuntu, which easily facilitate an entry point to their system using a graphical installer. I am not making a value judgement on which is better for Linux distributions, but attempting to demonstrate the fundamental difference. Bootstrapping a graphical installer with documentation is of marginal value for all but the most fundamental of users, but the lesson here will become obvious in future articles.

Second, this facilitates a culture of self-service. Users of the system, know the documentation is the entry point and therefore use this documentation. Obviously, the more they use the documentation and the more successful the outcomes they have when using it, the more they will use it.

Finally, this use of documentation is self serving. Passionate developers, architects and implementers are freed to move on to new and interesting projects, knowing that what they left behind will provide value to the members of their operations team. Also, the documentation process becomes more challenging, which makes it’s creation more intellectually stimulating.

In Part 2 I will expand upon Documentation Bootstrapping while in Part 3 I will explain how we are using it to successfully bootstrap two data centers which includes Power, HVAC, Network, Server, and Application infrastructure. This process is critical when you control such a large continuum of technology from physical infrastructure to bits you coded yourself.