Documentation for system administrators

Writing and maintaining documentation is something most system administrators don't like. Experience learns that documentation is seldom kept up-to-date after delivery.

In my opinion, this has two reasons:

  • System admins don't see the use of documentation, because they experience very little profit from it;
  • Documentation is hard to change (mostly because of procedures) and it is unappreciated work.

It is useful to give both issues enough attention. For system administration documentation it is certainly useful if admins can find relevant information easily.

Searching

In Google one can find an answer on a technical question usually within 30 seconds by stating clever chosen search terms. Searching documentation on a network drive within the company, usually organized in a very deep directory tree, takes much longer to finish. This is very frustrating to the system admins, who prefer to use Google to find answers, even when the answers are available somewhere in the system documentation.

Changing 

Changing is not very rewarding. After changing documentation, it is not visible to others easily what changed and who did it. For these reasons much documentation is not updated at all.

Wiki's

Modern technology can solve much of the described problems. Using Wiki's with search capabilities, for instance. The success of wiki's is best seen on http://www.wikipedia.org, where many people voluntarily invest much spare time in updating and creating articles.

People don't have to document articles on Wikipedia, but they want to do it, even for free. The reason is visibility: the whole world can see what you did and if you amend or improve documentation, your name is connected to this forever. Also information ypu created is easily found in Wikipedia.

Murdoc

My open source project Murdoc is a simple, but handy tool for exposing (already existing) documentation via a web interface with search capabilities. It is even possible for computer systems to be documented automatically, so the documentation is always up-to-date.

Murdoc contains a standard directory setup in which system administrators can organize their documentation.


This entry was posted on Friday 22 December 2006

Earlier articles

Infrastructure as code

My Book

DevOps for infrastructure

Infrastructure as a Service (IaaS)

(Hyper) Converged Infrastructure

Object storage

Software Defined Networking (SDN) and Network Function Virtualization (NFV)

Software Defined Storage (SDS)

What's the point of using Docker containers?

Identity and Access Management

Using user profiles to determine infrastructure load

Public wireless networks

Supercomputer architecture

Desktop virtualization

Stakeholder management

x86 platform architecture

Midrange systems architecture

Mainframe Architecture

Software Defined Data Center - SDDC

The Virtualization Model

What are concurrent users?

Performance and availability monitoring in levels

UX/UI has no business rules

Technical debt: a time related issue

Solution shaping workshops

Architecture life cycle

Project managers and architects

Using ArchiMate for describing infrastructures

Kruchten’s 4+1 views for solution architecture

The SEI stack of solution architecture frameworks

TOGAF and infrastructure architecture

The Zachman framework

An introduction to architecture frameworks

How to handle a Distributed Denial of Service (DDoS) attack

Architecture Principles

Views and viewpoints explained

Stakeholders and their concerns

Skills of a solution architect architect

Solution architects versus enterprise architects

Definition of IT Architecture

What is Big Data?

How to make your IT "Greener"

What is Cloud computing and IaaS?

Purchasing of IT infrastructure technologies and services

IDS/IPS systems

IP Protocol (IPv4) classes and subnets

Infrastructure Architecture - Course materials

Introduction to Bring Your Own Device (BYOD)

IT Infrastructure Architecture model

Fire prevention in the datacenter

Where to build your datacenter

Availability - Fall-back, hot site, warm site

Reliabilty of infrastructure components

Human factors in availability of systems

Business Continuity Management (BCM) and Disaster Recovery Plan (DRP)

Performance - Design for use

Performance concepts - Load balancing

Performance concepts - Scaling

Performance concept - Caching

Perceived performance

Ethical hacking

The first computers

Open group ITAC /Open CA Certification

Sjaak Laan


Recommended links

Ruth Malan
Gaudi site
Esther Barthel's site on virtualization
Eltjo Poort's site on architecture


Feeds

 
XML: RSS Feed 
XML: Atom Feed 


Disclaimer

The postings on this site are my opinions and do not necessarily represent CGI’s strategies, views or opinions.

 

Copyright Sjaak Laan