Documentation Plan
Before I describe the overall plan, I’ll describe my plan for documenting everything. There are a couple of reasons I’m going rather formal for my home data centre. They’re actually pretty close to the reasons you go formal with an actual data centre, to be honest.
Justification and goals
The chief reasons I’m tackling documentation in this way are:
-
I keep forgetting how I built something or where I got with something I haven’t finished building some months ago, so I waste time re-learning, re-discovering, etc.
-
I lose root passwords. This only happens for non-critical nodes, but these nodes too often wind up being important.
Some decent other reasons which I know will be beneficial:
-
Documenting a procedure means next time things will be much faster and easier to improve. Builds will be more consistent and it will be much harder to forget critical commonalities such as backups and logs.
-
Documentation forces you to think more about your decisions, or to examine what are not decisions but should be.
Knowledge targets
There are two areas I’m targeting for knowledge capture: basically the chief reasons, above.
Procedures
Procedures are recipes for deploying systems and/or services. They are step-by-step instructions with necessary justification for each step and references to the source material.
The references are important as they enable me to check accuracy–sometimes when I come back to something after a time, I interpret it differently than the first time around–as well as check for updates.
System information
There are two facets of system information to capture: system specifications and the root passwords.
System specification may be the least important. I tend to remember the basic specs of each node in my home datacentre, except for, as previously mentioned, root passwords. Sometimes I do forget details such as which node has the larger storage and I have two older netbooks, one of which has Gig-E and the other only 100M Ethernet. There is a bit of risk here in the trade-off of utility of information vs. maintenance cost + potential for losing currency. I’ll see how this goes. Making it easy is important.
The root passwords are important. They are rarely used and for the most part unusable, but they are good to have in some cases. They must be kept secure, obviously.
Implementation plan
I have been using Hugo quite a bit lately: for example, this site. Hugo is a static site generator which allows me to easily keep notes using Markdown in text files under a Git repository. It is quite flexible and supports different themes. I’ll assemble a custom theme for this site which will be very simple and support printable documents. Parts of the site will be printed on occasion and a copy kept in a special Operations duotang for offline reference, but the site will be up and available locally on my home network. I plan to maintain a GitLab service for this (as well as other sensitive projects, as I have in the past).
Procedures will be stored as blog posts, probably. The document classification is somewhat arbitrary, but it works. These may or may not be printed. Some critical base procedures may be, such as if I installed a modern uninterruptible power supply (UPS), for example, but I don’t need a hardcopy of how I build an LDAP service.
System specifications will be printable, and kept in the Operations duotang. In the case of something happening to me, this information would enable somebody with no familiarity of the pile of computers to figure out what is where and what’s important. Specifications, however, will not be stored as documents: Hugo supports storing structured data in YAML files, which are then interpreted by the layout templates and rendered in a readable form. By establishing a model in these YAML files, keeping the system specs current should be straightforward even if I haven’t added a new system in two years.
Passwords will not be stored in Hugo at all. The single copy will be handwritten on loose-leaf lined pages in the duotang.