Good Documentation Praxis

UPDATE (16.10.2011)

Hi girls and guys,

whenever there is something to reinstall or to recover there might be some additional tasks to fulfill to get everything back in the state it's supposed to be. Sure backing up a system often can safe you a lot of effort, but what's also necessary is to document your system and keep track of the things you are changing from the point on you are going away from a fresh vanilla setup.

There are several reasons why you should doing this and i will list them shortly:

Fixing Issues can often be a lot easier when you know exactly what has changed, which software was installed or upgraded recently and which configuration settings have changed.

Along comes the time where you have to get the hard track of a task that is very complex and a good documentation of your tracks can save you a lot of time.

On such systems where more than one administrator does the job documenting for others, so they are able to follow the steps your were working on, makes life for everyone a bit nicer.

Also it can be a good method to write down what you want to implement/deploy later on for your system.

So that nails it down to 4 very simple document entries in my personal Wiki:
Bugs --> where you describe errors and unusual behavior for yourself and others.

Howto --> where document stepwise what you are doing to fulfill a major task such as setting up a Web server for example.

Last action taken --> where you document whenever you change something on the system. Here you should also document whenever you update certain packages or change even big things.

Todo --> Tasks you not yet have managed to do, because of lack of time or maybe because you need to inform yourself how to get this done.

You can use a Web server based Wiki but you may want to give zim or rednotebook a try to accomplish this.

But using a wiki is only half the true. You also should comment your work. That means whenever you change a line in a configuration file, document it and whenever you are writing a programm or a script comment what the lines are meant to do, especially those line where you where sitting hours figuring out how to accomplish a particular task.

The next step is what is called a versioning system for your /etc folder. You may want to use the etckeeper. Since i use git for developing, i will use
git as version controling with etckeeper. I am not going in detail how to use
and install etckeeper since there are several blogs out there discussing this topic.

http://bryan-murdock.blogspot.com/2007/07/put-etc-under-revision-control-with-git.html
http://www.jukie.net/~bart/blog/20070312134706


You also should keep an eye on the history command. Some Editing may safe you time and work
in the future. So go on and edit your local or your global bashrc...
First expand your history from the default size of 1000 to maybe 100000 by changing or
definig these variables in your bashrc

HISTSIZE=1000000
HISTFILESIZE=1000000

If you want knowing when a specific command was executed, you may want to set the HISTTIMEFORMAT varibale, which is normaly not set. For example i set this to:

HISTTIMEFORMAT="%F-%M-%S --> "

So my History output looks like this:
996 2011-09-30-05-08 --> pull -u
997 2011-09-30-05-08 --> git pull -u
998 2011-09-30-05-08 --> cd

Preventing duplicated lines can be archived by
HISTCONTROL=ignoredups

Also you may want to set the HISTIGNORE variable:
HISTIGNORE="su *":"sudo *"

to avoid that somebody can determine which command were exacted by root.

that's all for today