90% automation on system documentation

In all the jobs I had until now,

most of the system documentation did NOT include why the machine was set up
or what one had to do to get common things done, but many people think, listing
all the hardware, serial numbers and installed software packages is sufficient.

I don't think so, but I think that these pieces of information should be included
into the documentation. But how do you do this without too much work?
You COULD collect all that information manually and type or cut&paste it into
your existing documentation.

I chose a different way: On many systems, we already collect data with the
neat cfg2html script. It collects most
vital data of many different operating systems and outputs them to a text or
html file.

I'm using the text file to create a Docbook appendix which I can include into
my documentation. I must admit that it's not the most elegant way to do this, but I had to write up documentation for >20 systems lately and this came in quite handy.

Now the script itself is pretty simple:

#!/bin/sh

# Give some advice if called with the wrong amount of arguments
#
if [ "$#" -ne 1 ]; then
echo "Usage: $0 <inputfile>"
echo
echo "This script converts the textual output of cfg2html"
echo "to an appendix to be included into docbook xml documentation."
exit
fi


INPUTFILE=$1

# print DocBook 4.4 appendix header
#
cat << EOF
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "/usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd">

<appendix id="cfg2html">

<title>cfg2html Output</title>
EOF


# Grep section names from the cfg2html file and create DocBook sections from them
#
# First, search for and remove section title decorations("---=[ " and " ]=---")
# and for each section title, put all the text between the separators into a
# <screen> tag.
#
egrep '^---=' ${INPUTFILE} | \
sed -e 's/^---=\[ //g' -e 's/ \]=---.*//g'| \
while read sectname; do
cat << EOF
<section>
<title>
EOF

echo $sectname | sed -e 's/ \& / \&amp; /g'

cat <<EOF
</title>

<para><screen width="80"><![CDATA[
EOF
sectname=$(echo ${sectname} | sed -e 's,/,\\/,g')
sed -e 's/ \]=---/ \]=---/g' ${INPUTFILE} | \
sed -n "/^---=\[ $(echo ${sectname}) ]=--.*/,/^---=.*/p" | \
egrep -v '^---=' | \
sed -e 's/ \& / \&amp; /g'
cat << EOF
]]></screen></para>
</section>
EOF
done

cat <<EOF
</appendix>
EOF




It does give a nice appendix including all the information found in the cfg2html output with
all the sections as bookmarks when you render a PDF from the DocBook file:




If you can't make the pasted script work, I'll put up the original file somewhere for you to download, but it really isn't hard

After you've saved a lot of time collecting data, spend it wisely, write down what makes that system SPECIAL, which things aren't the same as in your "Systems Administration 101" course, what are
the common pitfalls. Just consider this: You wouldn't let anyone drive your car who hasn't got a valid driving license, but you're documenting your systems as if your colleagues didn't know where to find the steering wheel. Keep it short on common topics, trust them to know what they're doing and
concentrate on giving them enough knowledge to work on things that aren't found in hundreds of books about system administration.