My template for technical installation documents

As a technical administrator, I often recommend creating high quality document deliverables. In a typical installation document, I am adamant about including certain sections which I normally don't seen many people add.

A copy of the template referenced in this post can be downloaded here.

While this document template is far from perfect, scroll through and learn what you can add that will help you make a standout installation document.

Be specific about the software versions you're installing.

No explanation necessary here.

Always include an architecture diagram.

The level of detail can vary, but a diagrammatic depiction of your architecture helps the reader visualize the end result.

Provide direct links to downloadable software whenever possible.

Include software and version, file name, size, checksum, and direct link to the downloadable software whenever possible. There will be no doubt what is needed when the reader attempts an installation.

Prepare a password list.

It's very possible that a single product installation may require the creation of tens of user accounts and passwords. Track the usernames in the installation document (but not the passwords!).

Document your bash or environment script.

Include specifics of your bash or environment script that's used in your installation.

Be specific in your installation instructions.

I'm a big fan of adding how long it generally takes to complete the section. That way, the reader has a general idea of whether the section he's following is a 4 hour effort or a 10 minute effort.

I'm also not a fan of screenshots in installation documents, especially if the instructions can be replicated by exactly following the steps documented. The overwhelming majority of authors who include screenshots do so because of the lack of confidence and poor quality of their instructions, requiring the reader to decipher and interpret what is needed from the screenshot and making adjustments to the instructions on the fly.

Always include a URL reference.

Add this as an appendix. Include every single accessible console URL.

Provide startup and shutdown commands.

This is a no brainer. The startup/shutdown reference should require the reader to simply copy-and-paste the command as is without thinking. If the reader has to customize these commands, then you have failed as an author.

Include fully qualified paths to all relevant log files.

Listing out all important log files make it easy for the younger administrator to know where to look.

Include instructions on how to check for services.

Provide one or more ways to allow the administrator to check if a service is up and running.