Many of us hate documentation, the writing, but love documentation, the well written. The well written build document is your safeguard to maximise your ability to rebuild your machine after deployment.
Although the Build Document is designed to provide consistency in recreating a specific system install, there are different thoughts on the how much information is required.
Step by Step Instructions. Some require build documentation to include every “screen” and the proposed “button/instruction” for the user to perform at this screen. This approach presumes little to no experience from the installer, but begs the question whether you really want someone who doesn’t know what to click on a screen, to be making this install?
This style of documentation is very difficult to maintain, and requires a lot of resources that in practise cannot be distributed.
Point form Instructions. Another choice of documentation is to provide documentation of point-form customisations to a “standardised” build of the Operating System and Applications/Services.
One advantage of the Point form instruction set, is that the Task Specific instructions are managed/updated separately, and can even be augmented through external resources (for example, use installation instructions documented/published elsewhere.)
Because the documentation can be split into discrete segments, it can also be distributed (or worked on by different people.)
Both techniques will get out-dated, the second should theoretically be easier to keep up-to-date because more people can be involved in the tasks.
One advantage of Task Specific documents is documenting validation procedures for each major component of your System Build, such as:
The extended/host variations will include modifications from the generic document for the host, and likewise all the validation/tests that are specific to this configuration.
Generic Information that are useful (independent of your choices above) include:
Hardware changes dramatically within the warranty period of your hardware, what you install your production system on today, is unlikely to be available before you need to replace the system.
Detailing hardware specifications can be very useful when seeking alternative physical hosts.
In some instances, configuration changes to the BIOS are required, such as specifying the drive type or changing the boot sequence.
What devices are being used to communicate with external resources? In most cases the only devices relevant to this section will be your network interfaces, but sometimes other tools are used such as Modems
It helps to specify the device and their configuration (such as IP Address for network cards.)
Operating Systems and Applications make presumptions about where files are stored.