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.
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:
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.
We have started to use DokuWiki where I work.
From Dokuwiki's website:
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.
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.
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).
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:
There are quite a few more customizations for Trac. It's not hard to setup and customize a Trac system to your liking!
In my previous work I used Twiki. It worked fairly well.
Next to that, I tend to automate most tasks, and document the scripts (not always with much enthousiasm, but still... ). Documenting scripts is easily done in the process of designing them, so no real overhead...
The combination of both (and using version control for the scripts) did the trick fairly well.
A mix of JIRA, Confluence and Word Documents.
Institutionalizing Knowledge
We started off with documents. Then we stored some of them in Sharepoint libraries. Then recently we moved to the Sharepoint wiki. I like the wiki's low-friction approach in quickly updating things, though Sharepoint's wikis leave some things to be desired in graphics support and formatting support for things like tables. It's fine for text and the built-in editor permits some basic HTML formatting and ordered/unordered lists. There are other low-cost alternatives to Sharepoint.
We also have sort of an informal knowledge base for our support tickets in our help desk software, Numara's Track-It. It's not perfect but it works.
Getting Staff to Use Institutionalized Knowlege
I would agree with your assessment that getting knowledge institutionalized is only one part of the battle. If your organization and people are not used to "research first, ask second" then you will find that the old way prevails: everyone will still look to the formal and informal gurus for answers, and for some people it will always be easier to ask the person next to you than to search on your own.
Dealing with this will involve some change management; like most successful change initiatives affecting more than just a small team, it'll help to have managerial endorsement and support. You really have to forge new behavior in two directions; someone needs to capture the knowledge and people need to use it. Even harder is that people also need to keep that data current.
Just some ideas: probably there will need to be encouragement in the form of a formal policy stating that solved tickets and issues need to be documented in the knowledge base or wiki before they can be considered closed. In addition, the knowledge leaders who normally get asked questions shouldn't always just offer answers on request; they need to point people to the wikis and get them used to checking there first. Another thing would be to make data available to users for self-help so the issue could potentially be resolved before it becomes yet another item the technical staff has to juggle.
What would be nice is for our help desk system to have a system similar to StackOverflow and ServerFault: when typing a question, the search engine finds similar items and offers them up, so users can look at them even before submitting the question.
In my last two places of work I used Sharepoint's Wiki, along aside with a document library which contained certain documents (such as DRPs and one time upgrade plans) which cannot be easily creates as Wiki documents. Those documents had links from within the Wiki. Wiki has many advantages in this area, as many people can edit it, versioning is built-in, easily searchable and accessible, etc. For quickly writing down notes or ideas, I'd use OneNote or a whiteboard.
I had created some knowledge bases before, in forum format (both in Lotus Notes and MS Sharepoint), but I must say that only rarely people are looking thru them in order to see whether a certain problem was already solved. Such a solution must come from day-one with a very strong and effective search engine.
If you want to create documents which can be used while you're at holidays, write them as if you're trying to instruct one of your parents. This isn't 100% fool-proof, but helps sometimes. Depends on who's reading it.
Sharepoint is nice.
It's search features have the ability to index almost any type of document, making searching documentation really easy.
It can do some templating as well which can make thing easier if for example you have a standard info sheet for each server you build.
It can also version your documents for you so you have an audit history of documentation changes.
Plus the files contained in the document libraries can be accessed over the web, in outlook, or via a unc share all right out of the box.