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

Computer crime

Introduction to Cryptography

Introduction to Risk management

The history of UNIX and Linux

The history of Microsoft Windows

The history of Novell NetWare

The history of operating systems - MS-DOS

The history of Storage

The history of Networking

The first computers

History of servers

Tips for getting your ITAC certificate

Studying TOGAF

Is your data safe in the cloud?

Proof of concept

Who needs a consistent backup?

Measuring Enterprise Architecture Maturity

Human factors in security

Master Certified IT Architect

ITAC certification

Open group ITAC /Open CA Certification

Human factors in security

Google outage

SAS 70

TOGAF 9 - What's new?

DYA: Development without architecture

Spam is big business

Why IT projects fail

Power and cooling

Let system administrators participate in projects

The 7 Habits of Highly Effective People

Archimate

A meeting with John Zachman

ITAC - IT Architect certification

Personal Information is Personal Property

The Irresistible Forces Meet the Movable Objects

Hardeningscheck and hack testing for new servers

Knowledge management

Information Lifecycle Management - What is ILM

LEAP: The Redmond trip

LEAP: The last Dutch masterclasses

What do system administrators do?

Is software ever finished?

SCADA systems

LEAP - Halfway through the Dutch masterclasses

Securing data: The Castle versus the Tank

Non-functional requirements

LEAP - Microsoft Lead Enterprise Architect Program

Reasons for making backups

Log analysis - Use your logging information

Archivering data - more than backup

Patterns in IT architecture

Layers in IT security

High performance clusters and grids

Zachman architecture model

High Availability clusters

Monitoring by system administrators

What is VMS?

IT Architecture certifications

Storage Area Networks (SAN)

Documentation for system administrators

Rootkits

Presentations: PowerPoint sheets are not enough

99,999% availability

Linux certification: RHCE and LPI

IT Infrastructure model

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