[colug-432] Documenting System Installation, Configuration, and Changes

[Neal Dias]

Very involved question, and you'll find lots of opinions on how to do this.

I've been a big fan of using native network installs,
kickstart/jumpstart/NIM etc. + a configuration management system tied
to SVN and a wiki.

The idea is that everything you put into the configuration management
is checked in/out of SVN, so you have a record of all changes. You
could go so far as to put your whole install into SVN, packages and
all, and let it track what you change, although that is a bit anal
unless you're trying to do build management, likely massive overkill
for one devel box, but then that would depend on how critical that
development is to you.

As mentioned, I'm a huge fan of wiki's, actually one particular wiki,
although it is not OSS, Atlassian's Confluence....

In a former life, I was trying to push for one of the org's I was at
to do something like this. The idea is that the build is documented at
the point of the build. All configurations are handled by a config
management system, you define in the CM how the system is to be
configured, then changes to the config's are done in SVN so they are
tracked. To do this successfully requires a shift in how most people
admin their systems. You would manage changes to the system by
checking things in/out of SVN where they are picked up and propagated
out to the target system, you generally would not use the CLI for
directly manipulating the system.

To be more retentive about it, you could use Atlassians Jira
(request/bug/ticket tracking) and tie it into the SVN repo. You would
open a ticket for whatever it is you're going to
change/update/install, you would check it into SVN, the ticket gets
updated by the ticket ID in the SVN commit, the CM pulls the update
from SVN and kicks it out to the system. Since Jira and Confluence can
be tied together, you can then include those Jira tickets, with the
associated SVN updates, into a Confluence wiki page. So you could have
a Wiki page that would show you what that system looked like at build
time, and then a historical record of all changes/updates to the
system.

An added benefit of doing this is that you now have both "live" and
"point in time" documentation....

So say I am creating build documentation for RHEL 6; that
documentation likely contains parts that are duplicated in other build
documents, especially if I'm working for a large bureaucracy. So using
the idea of includes, I can have separate wiki pages for different
sections of my document, but then pull those sections into one
coherent document that is in reality made up of many, many includes.
Maybe there are standard disclaimers an organization puts into a
document, or let's say I create a page that may be applicable to RHE5
and RHEL6, I can just write the section once, and then use an include
to have it become part of as many other documents I may wish. When
doing sales engineering, I did this for my RFE responses. I had
product documentation in discrete pieces, and then I could pull those
pieces into any document.

To me, the beauty of using the wiki is all the functionality I can get
from the plugins, such as PDF and MS Word exports/imports, as well as
version tracking. Let's say I'm finished with my RHEL6.0 build
documentation. I would export that into a PDF, a PDF I then attach to
a wiki page. That gives me my point in time documentation, but my wiki
is a "live" working copy of that documentation. When I'm ready to do
the RHEL6.1 documentation, I just keep updating my existing wiki
pages, so I have "live" documentation, and then when it's ready to
publish/release, I again export the wiki page out to a PDF and store
the PDF. I can also export the wiki pages out to static html that you
can host rather than your users hitting the Confluence install. So I
have the same documentation version controlled, with the text itself
version controlled, with the ability to export any version at any time
out to PDF/Word or html.

Anyway, I could spend literally hours on this, and to the chagrin of
some sales reps, I have time to time. =]

Here is a good write up on some of this. It's a little dated but still
a good reference.

http://jroller.com/TedHusted/entry/prim

You could also look into something like the Spacewalk project or RHN
Satellite if you want to spend the $$, but you'd still have to tie in
the documentation piece.

My quick $.02

-nd

On Thu, May 31, 2012 at 12:17 PM,  <jep200404 at columbus.rr.com> wrote:
> How do you document the installation, configuration,
> and changes to a computer? What are the best practices for such?
> This would be for a development computer where experimental
> futzing about is often needed.
>
> I mostly use plain text files with prose in chronological order,
> with occasional screen shots.
>
> I have been STFWing, but just finding stuff for how to install
> various vendors' add-ons.
>
> _______________________________________________
> colug-432 mailing list
> colug-432 at colug.net
> http://lists.colug.net/mailman/listinfo/colug-432