How do you document your sysadmin?

E

evanc72

After trying to organise my 7 years worth of documentation from MS to linux then FreeBSD, I have been hit by the revelation that my organisation skills really need an overhaul. ;) I am filled with chagrin!

With howto's and examples and then my poor efforts to document my server builds, I am seeking some advice from the gurus. I am self taught and have not had a mentor around to advise me on best practises with regards to documentation so if I may......

Here is what i would love to achieve.....

1) Interruption proofing - I am constantly having to leave my build or configuration to answer calls or go out and assist someone. I know I am not the only one, and a simple line "I am up to httpd.conf ..... " sometimes doesn't quite cut it. What's your method.......

2) A folder structure or file naming scheme for documents. Presently I have
Manuals => Server Builds
Manuals => Server Builds => backup configs
Manuals => Services (Howto's for httpd, bind, postfix etc...)
Manuals => Services => Examples (Real world examples from the net used for potential reference)

3) Method of documenting a server build - this is my greatest weakness as they end up messy due to unforseen issues that arise. 40 commands later - you find yourself scratching your head saying "Now.... how did I do that?"

4) Overview format for numerous machines. I have used vmware-server and the notes section for descriptions as a quick overview. Now I have moved to jails on FreeBSD7 I lack the visual overview and quick access to notes.



Now I do have a system that is usable - but very inefficient. File naming scheme may be the simple answer. If so - what is it you use.

As always - I appreciate your time and responses.
 
  1. Mediawiki => To keep track of special software config. Like /etc/sysctl.conf amd tweaks. http://www.mediawiki.org/wiki/MediaWiki. We have developed our knowledgebase (KB), tutorial, faq using this.
  2. RT => (enterprise-grade ticketing system) for customer support and it is one of the best GPL software around. RT manages key tasks such as the identification, prioritization, assignment, resolution and notification required by enterprise-critical applications including project management, help desk, NOC ticketing, CRM and software development. http://bestpractical.com/rt
  3. We have in house developed software to keep track of all hardware and network inventory. This software can answer any question like location of data center, server config, operating syste, hell it can reload os on demand.

Most above software modified and authenticate against central Redhat directory server. Customers have limited access to portal and all staff members have full access.
 
We use MediaWiki for this as well. Document the process as you go along, and keep it up-to-date. Even doing plain copy/paste dumps from your text files into a wiki is a good start. And it makes it available to more than just yourself, if need be.
 
Mnemosyne loves you.

evanc72 said:
3) Method of documenting a server build - this is my greatest weakness as they end up messy due to unforseen issues that arise. 40 commands later - you find yourself scratching your head saying "Now.... how did I do that?"
Click to expand...
Use sudo(8), which logs every use to /var/log/messages. It shouldn't be a big deal to archive this information and use it mnemonically.
 
Wow - Thank you everyone. I will look into Mediawiki.

I am surprised at the choice of web based content as opposed to a document management system. In reality documents are simply containers for content, held in various formats (text, html, odt, etc...) - so I see the logic.

So if web based content is the recommended format, why Mediawiki over other CMS. Example being

Joomla - Very light and flexible CMS
vtiger - Which is more CRM
Drupal - Big heavy CMS
Wordpress...... etc

I understand personal preference - but with 4 mediawiki responses........ what makes it so good?

Thanks again for your replies :-)
 
Why mediawiki?
Click to expand...
  1. Collaboration.
  2. Ability to do diff on FAQ / tutorial
  3. Fallback to older revision if needed.
  4. Discussion for each wiki page.
  5. Easy to use and learn.
  6. Anyone can edit (inside your office)
  7. Easy to follow syntax.
  8. Opensource software that runs on LAMP.
  9. Remember you are not creating content or portal, so why waste time with complicated things.
  10. Pizza .. oh wait..
 
Same basic idea, of course, but I document our systems using Dokuwiki (which is also in ports). I have baseline install / config pages for each OS and version, along with network notes, service descriptions and diffs (where changes were required), etc.

I also keep notes on some of the more useful commands that I expect to need for host level firewall changes and monitoring, jail management, user management, and a few others.

---

By the way, I am using Shibboleth authentication with Dokuwiki (our organization provides a Shib IdP), which is a snap to set up via a nice plugin.
 
You must log in or register to reply here.
Back
Top