3

I want to document any change I do to my ubuntu system. I want to do this in a way that if I had to pass this system to another administrator, it would be easy and logical for him to access this documentation and use it for any purpose. The main reason that I want to do this is so I can look back and see exaclly what's done to solve a problem and so on.

What would be the best way to do this? I am thinking placement of the documentation files and methods of creating and viewing them easily.

Another reason I want to learn good documentation is that one of the LPIC-1 books says this is very importaint, but does not elaborate much on the subject.

Hope this question was'nt to distro independent or unclear.

Update: (have made some ideas and more thoughts on the subject)

I've got a Dell Inspiron 1564 with BCM4312 wireless card on which the Broadcom Sta/wl driver caused kernel panic. I do not remember everything I tried to fix it, and I do not remember how exaclly I fixed the problem. I also have problems with my new driver, and I miss not having documented this locally.

What I want, is a folder which contains both documentation on what has been done, what is installed on the system and also perhaps HOWTOs for new desktop users. I want a pager, like less to display these files, and I want to use a good location to store them. (usr/share/doc?) This is in addition to commenting in config files and scripts.

I altso want to create a function that lists all the documentation. I think I need to write a script, with options to create, print and list my doc files. Am I on the right track at all here?

I reckon it is not actually necessary to write a script for this, but I think it might be good learning, anyways. I am thinking something simple like this:

  • docfile list #To list all doc files and howto files.
  • docfile -n or filename.howto #Create new/edit file doc tile
  • docfile #View file in pager like less

Yeah, I've got some time on my hands at the moment.. :)

To cut the question to the bone: I want a simple and elegant way to create and print documentation locally. Is the suggestion above (a script) a reasonable way to solve this? And where should I place these files? Is /usr/source/doc/docfiles the place to save them?

  • @Rinzwind: Please add a comment if this was the kind of you were talking about! Thanks! :) – Nullet Sep 15 '13 at 12:41
0

Create a script.

We have a post installation script for when we need to install a new server. After the basic Ubuntu server is installed we do a semi-unattended installation of apache, mysql and some other software. Then we extract an image with our software and settings for both apache (ie. site-enabled) and mysql (ie. my.cnf).

The fun part of Linux is that anything is a file so this script also has lots of "sed" statements that alter settings files from command line. Think along the lines of performance tweaks, cron jobs in /etc/crontab, our own log files.

Comments above the commands make sure anyone should be able to understand what is happening.

Having these things on paper only works in theory but after a while it is useless since people forget to update changes they made ... Having them in a script will have everyone updating this script (since it makes their work easier).

  • I am not sure you understood my question, and that I understand your answer. I will update my question for more details. Thanks! – Nullet Sep 15 '13 at 12:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.