48
votes

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.

4
  • your question just made slashdot tech.slashdot.org/article.pl?sid=09/05/25/2154237
    – username
    May 26, 2009 at 18:10
  • hehe :) I wish I could somehow conclude this question, perhaps wait for the beta to be over...
    – user1804
    May 27, 2009 at 9:48
  • See the "related" section in the sidebar - serverfault.com/questions/3970/… might be what you're looking for
    – Olaf
    Jun 4, 2009 at 5:02
  • Monitoring systems such Nagios tells you what your network/systems currently look like. They don't usually tell you why the network and systems are setup they way they are.
    – David
    Jun 5, 2009 at 16:12

34 Answers 34

8
votes

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.

1
  • 1
    I use ikiwiki on top of git. Also gives me markdown and disconnected operation
    – ptman
    Oct 18, 2010 at 15:06
7
votes

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.

6
votes

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).

6
votes

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.

6
votes

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!

1
  • 1
    +1 this. Not only does Trac's wiki make easy reading and editing for documentation. When used with issue ticketing and SVN for configuration versioning, you have seamless visibility of the entire workflow.
    – Dan Carley
    Jun 4, 2009 at 8:25
5
votes

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.

5
votes

A mix of JIRA, Confluence and Word Documents.

5
votes

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.

1
  • +1: Where I work, it was a similar problem with getting staff to use resources though, specifically, it was using the issue tracking system to get problems looked at. I ended up taking the people who had trouble changing their habit of interrupting me back to my desk the first couple of times and filling out a new bug ticket with them. Took 2 months and now everyone enters their own bugs and they all get taken care of in order. A similar approach might be useful here (ie. look for the document in question in the [system] WITH them) Oct 19, 2009 at 2:47
4
votes

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.

1
  • I agree that good search is absolutely critical to the use of these tools. Getting decent search into Sharepoint was recently achieved by a colleague, it's OK but it ain't Google.
    – user1804
    May 4, 2009 at 17:24
4
votes

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.

3
votes

We have used MediaWiki (with fckeditor) for several years, although I must say it would be nice if picture (ie screenshots) handling were easier. And while having the ability to search is essential - I find MediaWiki's search often misses pages. Perhaps that's just a matter of learning to search better (which kind-of defeats the purpose of having a simple way for others to do your work)

Right now we are in talks about moving everything over to MS Sharepoint, although not necesarily to their wiki. I think Sharepoint is able to do full document search in a way that negates some of the advantages of a wiki, so we'll see where this goes.

(not looking forward to the process of porting all our current documentation though :) )

1
  • 1
    I've read that Sphinx is a worthy addition to a MW installation, to improve search.
    – user1804
    May 4, 2009 at 17:19
3
votes

We're using a wiki. Sure the syntax took a bit to get used to, but the one we're using (twiki) stores its data entirely as text files. This allows us to easily read them in the event of a disaster, as we can restore them to anywhere, and search them from the command line via grep, and read them in any text editor we like.

Every server has a page, with a standard collection of sub-pages for change managment info, startup/shutdown, and configuration notes, as well as dns, firewall, and asset info.

2
votes

We're getting ready to move to some version of a Sharepoint service to try to get us off a mixture of word documents spread across three servers and who knows how many folders. Currently, we have a massive excel spreadsheet that contains hyperlinks to the documents that are described in it.

Not the best way to do it, but when the company started, they never planned out how to handle the internal documentation and left it up to each group to decide how to sort and store their own documentation as they saw fit. Now, we're trying to merge into a unified system, which will be around one of the Sharepoint offerings.

2
votes

In the NGO where i work we just use text files placed in a folder for critical procedures. Personally as a System Administrator/Web Developer hybrid i've been using a knowledge base of text files scattered on a tree directory, that's my Memex and i write down almost everything on it (personal,work,etc). This scheme is very easy to manage using Jedit a real swiss army knife for text processing, i've found its outline plug-in, code folding and hypersearch features indispensable. All this safely backed up by rsync to a ssh-accesible remote server.

alt text

Couple that with the Makelink Firefox Extension and you have the perfect bookmark manager.

1
vote

We use flexwiki, which is a dotnet and open source.

1
vote

Erm...how about Fogbugz? :)

1
vote

We are using ScrewTurn for content and SharePoint to store documents / images.

1
vote

There are some interesting things here - i like the one about the passwords in a safe.

1
vote

We use a combination of text files for quick searching with grep. And SharePoint for a more organized collection of in-depth documentation (Visio diagrams, etc.).

1
vote

As Google Apps (Enterprise) clients, we use the heck out of Google Sites -- their wiki "flavor." Easy to use and we've had great adoption from admins and developers.

1
vote

I didn't see this question before I answered another question, but here we go.

We use a number of tools and methods.

  • Functional specifications for infrastructure components and software.
  • Two Confluence Wikis. One for internal corporate documentation (policies, procedures, internal infrastructure and IT, etc) and one for our open source software products.
  • RSpec and Cucumber tests. Our software is mostly written in Ruby, and we practice BDD/TDD, so specification tests drive the actual code, and document as well.
  • Inline code documentation. We use RDoc markup in code comments.
  • Declarative configuration management (Chef). All our servers are managed with Chef, which "self documents" through delcarative resources in recipes and cookbooks.

We like Confluence because it is very flexible and powerful and feature complete, plus it ties into the ticket management software we like, Jira.

In previous companies I've worked at, I've used a variety of tools and methods and many have tried to stay with a single catch-all resource (like a Wiki) for everything. The problem with that is documenting various topics with a single tool not uniquely suited toward covering that topic means that many things won't get documented at all, because it is difficult to migrate the information. As a Unix/Linux geek, I believe that each task requires a specific tool, and that tool should fit that task exceedingly well.

1
vote

This question is very well a duplicate of this one and I moved my answer there.

1
vote

I do most of the documentation for my company, and the format that was established when I started working here was MS Word for editable originals, exported to PDF for read-only general releases. It works fairly well for projects where only one person is updating the document, and since that person is usually me, management hasn't seen a need to change.

We've started documenting our bugs and upcoming tasks with Trac, while using a "Peer Review" extension for code reviews. That has seen great acceptance from our team because it's simple to collaborate in and it's easy to navigate. A few other team members have expressed a desire to begin collaborating more with specifications, test procedures, and manuals, so we're looking into DocBook/XML exported into PDF for public documentation like manuals, and Trac WIKI pages for internal documents like specifications and test procedures.

In my mind, the biggest issues when choosing a documentation format are:

  1. Is it easy to create?
  2. Is it easy to maintain?
  3. Is it easy to maintain if someone else wrote it?
  4. Can it be exported/converted into other formats without much hassle?

1-3 make my life easier, and are important for producing documentation quickly without going insane. I think the fourth one is the most important on the customer end, because formats are continually going to change. Microsoft Word 2003 format isn't going to be around forever, and neither is our current implementation of PDF. I need to make sure that all of our customers can read our documents, no matter what their OS or document reader-of-choice is.

1
vote

We use MediaWiki with various plugins, including SemanticMediaWiki. SMW is nice because it turns our MediaWiki installation into a big, free-form relational database that can be queried at will. Need to know which server a website's on? Visit it's page. Need to know what websites are hosted on a server? Run a query, and it'll pick the page names out based on the proper tag on each website's page.

1
vote

I will answer not with a documentation system I have used, but with something I have seen used and which I find very good: http://stackexchange.com/

stackexchange is the Q&A platform that runs under serverfault (well, technically it's not exactly the same, but for our purpose here we can assume it's the same).

Fogbugz uses it.

There is an interesting blog post from a Fogbugz employee where I found these quotes:

For all purposes outside of product specs, I think corporate wiki’s and discussion forms have been dealt a fatal blow.

...

Since we’ve begun using FogBugz.StackExchange.com as our support platform, I’ve never answered the same question twice. We even have an internal SE server which we use for non-public-facing Q&A, and the same principles apply there.

They use stackexchange for customer-facing knowledge base and internal knowledge base.

I am interested to see if such knowledge exchange Q&A platforms will replace corporate wiki's.

0
votes

At my previous employer I used Word, Excel, and Visio files collected together in a folder. A hard-copy of everything was kept in a binder in my desk. I was the only IT person so there was little need for anyone else to have access to the information.

At my current employer we use Macola ES by Exact Software, but I still prefer to write my documentation in Word and upload it into Macola as an attachment than use the built-in document editor.

0
votes

At my workplace, I dropped ScrewTurn Wiki on one of our Windows dev servers and hooked it up to our SQL Server. It works really well, runs quickly, and mainly stays out of our way for documentation. In the two weeks since it's been deployed, we've already added about 60 pages of information, and it's only for our team (~10 people).

So far, we keep information about current and past projects on there, and have started adding information about the applications such as how to build them from scratch, URL's, and other important information for dev's new to the team.

One of my favorite pages on the wiki has been the tools and libraries page. There, we've started adding information about our favorite productivity tools and libraries that we use a lot, an example of which is grepWin for text searching in Windows.

I would fully recommend checking out the full gamut of wiki's available and find one that suits your intended usage, functionality, and deployment environment. I chose ScrewTurn because it's easy to use, and we had a ton of free room on our local WinServer, but YMMV.

0
votes

We are using Confluence as wiki and sharepoint for documents in some cases. I believe that online wiki format is a prefered one when you need to share this information really widely and what's much more important when documents are going to be edited and updated very often. So I think the knowledge base articles it's better to put in wiki.

0
votes

We are currently moving our info from various documents spread around the network to two locations:

  1. A wiki available on our intranet
  2. A copy of the information related to a particular server in that servers /root directory.

For network diagrams, Network Notepad.

Also, while recording the what, remember to record why something is configured like it is. This helps prevent ideas that seem like a good idea from turning into mistakes.

0
votes

We've found that MediaWiki has been a slow starter, but once folks outside of IT got wind of how easy it was to add comments, changes, edits etc., it's become indispensable. Developers are using it for internal documentation, facilities dept. for posting notices, etc. It's grown beyond just being an IT documentation tool.

You must log in to answer this question.