How are you documenting your work, processes and environment?

Are you using a wiki format? If so, which product? (MediaWiki, Confluence, Sharepoint etc.)

Have you create a knowledge base? (Problem/solution-oriented short documents.)

What challenges do you find with creating documentation that works, so you don't get the call when you're off on holiday?

For me, I find there is often a certain amount of organisational "inertia" involved with getting documentation done. It seems to be a different kind of person who can do a task, then think about how they did the task and describe it so someone else can do it - kind of forces to you "go meta" and not everyone is comfortable doing that.

Update

Answers so far include

• Confluence
• Flexwiki
• Fogbugz
• Mediawiki (with plugins such as fckeditor)
• Sharepoint
• TWiki
• Word/Excel/Visio Docs
• Documented Scripts

Edit: Aren't you implicitly documenting your network with your monitoring system? Nagios has always encouraged the use of the parents directive to reflect your network's structure, and the notes_url directive is designed to allow you to link to a wiki or other browser-based documentation. So here the "documentation" is split between the "living document" of the monitoring system and more detailed, offline documentation in a wiki. Since I spend a lot of time staring at Nagios it makes sense to put effort into making it as informative as possible.

Solution 1:

Commenting on the tooling.

We've tried online wiki's but found a number of limitations, which may be personal taste, but include document structure and most critically having to be connected to the documentation server.

Being connected is a serious problem if you are either offline or onsite (obviously you can mitigate the onsite with a secured SSL connection et. al.)

Our current documentation process is:

• static html generator
• markdown syntax
• distributed versioning system

We have a 'formal' layout for the documentation and that provides the structure for the menus (and the associated CSS for visual styling etc.)

Static HTML Generator

We use an in house static html generator based on cubictemp and a number of other tools: pygments, docutils.

The generated pages are (not?)obviously ugly looking, as most of us/our sysadmins/programmers know what is aesthetically beautiful but have a total lack of coordination into building such.

But it affords/let's us include configuration files, sample scripts, pdf, etc, without having to worry about html formatting screwing it up or worrying about where to find it on the 'server' for downloading.

If it's not HTML, just drop it in the folder and add a url link to it.

HTML provides 'potential' structure for layout, and also critically provides 'linking' between knowledge/content items (as well as base structure mechanisms, such as being able to create menus, table's of content etc.) With HTML, each user can now run a small web server on their machine whether lighttpd or something small or just go full blown with Apache or IIS.

All our machines have the grunt for basic html serving, and works well enough for us.

MARKDOWN syntax.

We use a bastardised version of MARKDOWN, Textish and or reStructuredTEXT to let our 'creative' juices write documentation without having to worry about HTML.

It also means everyone get's to use their favourite editor (I use Scintilla on Windows and *Nix) while the others here use vi/vim.

Distributed Versioning System.

We use Git to 'distribute' the documentation between users. Oh, and we use it's versioning capacity too.

The key advantage for us is that we can all work on updating the documentation without having to be connected to the server, and without having to publish 'completed' works. We can all work on the same parts of the documentation, or different parts, or just consume the information.

Personally, I hate being tied to a server to update blogs let alone wiki's. Git works well for us.

Commenting on the Workflow

Wiki's seem to be the "fashion" for knowledge dissemination / codification, but as commented elsewhere all processes become difficult to sustain, and finding the mix of tools that best supports your teams needs and is sustainable will take time.

The better solutions just end up being discovered and not mandated.

Solution 2:

We have started to use DokuWiki where I work.

From Dokuwiki's website:

DokuWiki is a standards compliant, simple to use Wiki, mainly aimed at creating documentation of any kind. It is targeted at developer teams, workgroups and small companies. It has a simple but powerful syntax which makes sure the datafiles remain readable outside the Wiki and eases the creation of structured texts. All data is stored in plain text files – no database is required.

I found Dokuwiki the easiest to implement because it requires no database, and it was easy to setup. There also were add-in modules which made enabled to use my existing Active Directory account logons rather then having to create accounts for everyone, which was a huge plus over much of the other wiki systems I found. it also has the typical versioning control, where you can see who posted what where, and it has the ability to roll back to a previous version easy if necessary. They also include a customizable home page which where yo can easily change out whatever type of content fits best for your environment.

Solution 3:

Doku Wiki or Sharepoint for other things that fit into a chart.

You get used pretty fast to posting on a wiki and the syntax is not so complex really. It is very easy to organize information and make it easy to find it later on by someone else.

I use visio to make graphs for clearer explanations (export as JPEG).

Solution 4:

We're using a wiki. In fact, we're using MediaWiki. On top of MediaWiki, we have the Semantic Mediawiki extension installed, which actually turns our MediaWiki into something of a loosely typed database that we can query with Category, title, contents, etc.

For instance, let's say I want to see all the network cnames that route through Cluster F. All I need to do is use the Special:Ask page to query [[Category:cname]] [[destination::cluster_f]] ... and it'll return all the pages that are categorized as a cname with the destination as cluster_f.

We support a couple hundred very disparate customers, so having that documentation in a central place (and having it cross-linked so that the special cases stay documented and tied into the whole) is a huge handy thing. Obviously, our documentation needs to be maintained, but you can take more of a 'gardener' approach to the maintenance because the mediawiki toolkit for keeping a large dataset current is already fairly mature.

Solution 5:

With the right plugins, Trac can become a combination ticket and wiki system. This makes it easy for your tickets to link to wiki articles and vice versa.

A couple of plugins I like:

• Private Tickets plugin. Trac is built as a bugbase where all tickets and their responses are public. That's not appropriate to an IT ticket system, but this plugin fixes that.
• Trac WYSIWYG plugin. Let's face it, most people are not going to learn wikisyntax to make you happy. This gives them a 'what you see is what you get' editor for both tickets and wiki pages.

There are quite a few more customizations for Trac. It's not hard to setup and customize a Trac system to your liking!