How do you document your environment ?

[Sebastien Masson]

Hi all admins,

This is an open question and your input will be very nice.

I have a kind of a huge "mostly" undocumented environemnt and my Boss ask me to document everything. No prod! - I said. But where I should start ? What I should add ? How I should document all those systems ?

My question is how do you document your environment ? How do you prevent your documentation to be obsolete by too much change ? Do you do a document for the design, another one for the operational task, etc ?!

Thanks

[Mel Burslan]

Most important task in documenting your environment, in my opinion of course, should be able to create a document to allow you rebuild the system, should a catastrophy strikes. For this purpose, yo need to know what your system is comprised of. For this purpose, I personally use cfg2html script that comes bundled with measureware software but you can download it from pretty much anywhere but mainly from its home page

http://www.cfg2html.com

For the same or very similar purpose there is another piece of code called nickel, which can be obtained from:

ftp://ftp.hp.com/pub/catia/Utils/nickel.shar

After this, you are on your own to interview the business unit running any applications on this system and get their application install documents, how their data is structured, what database it run on (let's be frank, most applications run on databases nowadays), and its dependencies.

If you are a good technical writer or have one like myself that you can dum a bunch of technical doc.s and get a nice document in return, you are in luck.

Hope this helps.

[Adisuria Wangsadinata_1]

Hi,

For me, the documentation are :
- for hardware configuration
- for software configuration
- for daily tasks (as our SOP : standard operation procedure)

1. The hardware configuration
I use Visio to draw the hardware configuration (the system, the cabling for network & power-supply). If you use visio, you can have the template from this url :

http://www.visiocafe.com

2. The software configuration
I use nickel script and cfg2html script to get informations from the system. To be safe, I create folders for each of my HP-UX system (soft copy & hard copy). Check the reply from Mel Burslan for the url.

We also document on every codeword that use in our HP-UX environment.

3. The daily tasks
The purpose of this is to delegate the tasks for other person who knows about the HP-UX environment when the admin is not around (eg. sysadm asst). For example : how to run the backup/restore, how to trimmed the system log files, how to power-on/shutdown the system, etc).

We also create the folder with necessary document that related with our environment, so it will make us easier to get the documents.

With all the documents above, it will help us to make more 'easy' the jobs in the future.

Hope this information can help you.

Cheers,
AW

[Yogeeraj_1]

hi sebastien,

you can also run stm to generate a report on your hardware.

Measureware will allow you to generate report on your current system performance (cpu, memory usage etc..)

hope this helps too!

regards
yogeeraj

[Sebastien Masson]

It's a good start. Just let you know that I mostly know all generated doc software like cfg2html or nickel.

My problem is not how to generate those doc but how you organise them together in something useful.

It's very important for me that everything is keep somewhere in case admin leave the cie.

Thans for the SOP part. Very interesting.

[Adisuria Wangsadinata_1]

Hi,

In my environment, we put all the document in the folder that can be accessed by IT people only (of course this only softcopy part)

Let say the folder is HP-UX (since your enquiry on HP-UX forum), and under this there will be a folder for hardware, software, SOPs and manuals ... or you can add another one call 'misc' :-)

More you manage the folder, it's easier you get the info.

Cheers,
AW

[Mel Burslan]

We internally use the file control system, visual source safe, from the Darkside, a.k.a., Microsoft. Even though I do not like it too much, as the corporate standard is M$ office, this one ties into the office products real well, with delegation of file modification and ownership privileges. In my opinon, this is a little bit of an overkill but hey, it is the document knowledgebase not only for hpux but all OS platforms and applications supported. We just delegate the collection of mundane data, like disk devices, tapes etc. to the operators. And they check the initial doc.s to the VSS database. We, the sysadmins, approve or modify these initial documents and claim the ongoing ownership of the doc.s.

I am sure any CVS package, can do the same thing without added cost of microsoft licensing if you are starting from the scratch.

HTH

[Muthukumar_5]

You can generate machine related informations such as RAM, DISK, CPU, TAPE, IP-Address, MAC Address, Interfaces and etc from that machine with tools like sam or sysinfo script or related scripts.

Environment documentation will be needing Network diagrams, switches, routers etc.

Use some pictures available as,

http://www.homenethelp.com/web/diagram/index.asp
http://www.conceptdraw.com/en/products/cd5/ap_network_tool.php (commertial tool)

hth.

[Muthukumar_5]

A free tool as,

http://www.weresc.com/network.php

Example:

http://www.smartdraw.com/examples/networkdesign/computer_lab_network_diagram.htm

hth.

[Arunvijai_4]

LanFlow Net Diagrammer is a very good tool for designing your network and other stuffs.

http://www.pacestar.com/lanflow/index.html
(30 days trailware is available)

-Arun

[Yosef Rosenblatt_1]

Mr. Masson,
Your question indicates to me that you currently have no documentation and that you are unsure of what documentation you need. Reading through the postings I see that the members have given you a lot of excellent advice. If you follow all of it you will be even more confused than you are currently.

As Mr. Burslan pointed out one of the most immediate needs for documentation is DR, disaster recovery. I therefore suggest that you look at DR planning, DRP, materials. DRP methodologies will help you understand what to document and how to do it. Choose the methodology that suits you and your company best. DRP requires that you document your systems, environment, hardware, software, â peoplewareâ , methods and how you do business as an IT department.

By following a single plan of attack you can conquer the mountain of work that lies in front of you. In the end you will have a document that you can use rather than an accumulation of unrelated papers. Because this document will have structure you will be able to modify it without having to re-invent it every time you add a new system to your environment. It will become a living document that you can use for years to come.

HTH,

Yosef Rosenblatt

[Sebastien Masson]

Thanks for all your reply. But like I said, my question is not how to generate the documentation. Right now, I have a folder full of all kind of document, few tools that generate some too.

My question, again, is mostly how you organize that togheter. Me, right now, all my documentation is under CVS organized in folder structure. But in this situation, it's easy to create new doc and lost control on what is good, obsolete, etc.

So my idae what to create 5 big documents:

1. Reference Guide

Contain all environment constant like
S/N, contact, URL, License, etc.

2. Design and Architecture Reference

Document how each element in the
environment was build to help any
kind of troubleshooting

3. Operational Guide

This is the procedure gudie that explain
the day 2 day jobs. Devide in kind of
what you need to do each day, each week,
each month, etc. Each task is
documented in the (HowTo Library)

4. HowTo Library

Contain a section for each step by step
process. So I can build more complexe
process by reference to some simple other
process. This is use in the operational
guide.

5. Checklist Collection

Contain forms, or process checklist that
the operational people may print out and
use when they follow an operation task to
not forget any step.

Give my your opinion on that. Do I miss something here ?

Thanks

[Geoff Wild]

We setup Mambo (now Joomla) for our documentation.

http://www.mamboserver.com/
http://www.joomla.org/

We have multiple addmins - we do a lot of docs manually - and Mambo makes it easy to enter and edit and organize.

We also provide links from mambo to sysinfo, cfg2html generated pages as well.

Rgds...Geoff

[Marvin Strong]

Personally, I have a folder for every system (hardcopies in my desk) that contains, visio diagrams, print manifest output, some other documentation, standards, disaster recovery documentation, license keys for software etc..

Other places I have been used a shared folder, that contained all the information, so that all admins or managers(they seem to like visios) had ready access to the information, good idea IMO. If you have the disk space, and a secure place to put it.

Of course the bigger trick is keeping the documentation updated with changes, many times I will find some very good documentation. Only that it outdated and no longer useful.

[Rick Garland]

Use cfg2html

I keep the html copies on 2 different systems, both have http processes running so I can access. I also keep previous copies of the output on a third system for up to 6 months.

I also keep hardcopy outputs as well

[Steve Lewis]

I also have a site on our company intranet for my server configuration html files.

I extended the config documentor script with my own stuff e.g. passwd file extracts, full stm device firmware versions etc.

I take photographs of the systems, front and back, because my servers are 200 miles away from me. The photos are a boon when it comes to upgrades - you can see which i/o slots are free, how many trays in your disk arrays etc.
Photos are also a good idea if you are a consultant and have many customer systems to document - the HP support agreements aren't always in sync with what you see plugged in.

I also wrote a simple web form and couple of CGI scripts which allows you to compare two server configuration files (Samba mounted) in order to find server differences. This has been good for SOX and SAS-70 compliance. Each machine re-documents itself each month and sends the files to the webserver, which reports on the differences, patches, hardware, users, filesystems, logical volumes, releases etc.

[Tim D Fulford]

Hi

I've just been reading this and really feel sorry for you. I'm lucky enough to be working in a "product" based environment. This means we have ONE build document, ONE database tuning document and so on... the only thing missing is the architecture. This does vary and I use visio for this (www.visiocafe.com).. I also user print_manifest; from Ignite-UX (but I think cfg2html has this also)...

What we do is advertise the results on our intranet...

anyway, good luck... you have a large task..

Regards

Tim

[Steven E. Protter]

I have scripts.

I document procedures and dump them an internal web server.

I would start with a simple docsys.sh script that collects information on the system.

If you want something nice and web based then try a product like wiki. If you can get it working, which I can't right now, you can cut and paste out of your keyboard log and great wonderful, searchable documentation.

SEP