How are you documenting your work, processes and environment?

Question

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.

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

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

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

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

Answer 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!

Answer 6

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.

Answer 7

A mix of JIRA, Confluence and Word Documents.

Answer 8

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.

Answer 9

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.

Answer 10

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.

Answer 11

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.

Answer 12

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

Answer 13

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.

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

Answer 14

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.

Answer 15

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

Answer 16

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.

Answer 17

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

Answer 18

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

Answer 19

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.

Answer 20

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

Answer 21

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.

Answer 22

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.

Answer 23

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.

Answer 24

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

Answer 25

Erm...how about Fogbugz? :)

Answer 26

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.

Answer 27

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.

Answer 28

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.

Answer 29

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.

Answer 30

MindTouch Deki (also known as DekiWiki or "MindTouch") is my choice here, for a number of reasons:

• it looks and works great out of the box, but is also easily extensible with extensions, scripts or templates
• it uses a WYSIWYG editor, so users can't use "I don't want to learn wikitext" as an excuse to not document
• all the data is stored in XML, which means every page can be operated on as an XML web service
• easy-to-use API, operated on with REST (standard HTTP verbs)
• fantastic scripting language, DekiScript, making mashups trivial
• absolutely beautiful PDF output using Prince, the HTML/CSS engine from the authors of CSS

How do I use it? As a complete knowledge base, divided into sections for each department, with pages under that for anything that might need information stored about it!

Regarding network monitoring systems, you can download a Zenoss/MindTouch Deki mashup for placing live data from a Zenoss installation into MindTouch wiki pages for things such as configuration notes and other possible future mashups.

The open source edition is marketed as "Core", and add-on features in the commercial edition include connectors for services such as SugarCRM and Salesforce, and databases such as Microsoft SQL Server. Commercial customers also get access to Windows connectors (Outlook/Word etc) and a dektop application for manipulating the wiki.

Installation on IIS is as simple as installing MySQL and then installing a MSI. The MSI is technically only for the enterprise edition but there are workarounds for using it for the open source build. An alternative is installing the VM appliance (especially if you already have a VMware server infrastructure), in which case you really don't need any configuration at all.

Answer 31

Try Redmine. I've used it for College group projects as well as Industry projects.

It includes support for wikis, documents, notes, svn (I believe they are working on git), feature requests, sophisticated bug tracking and everything is automatically added to gantt charts to monitor development.

It is a VERY nice platform where you can add different levels of users (devs, observers, users, etc) and share lots of information between everyone.

http://www.redmine.org

Answer 32

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.

Answer 33

MediaWiki here too. I am the sole IT support in the accounting firm I work for, so at this point I don't need to worry about collaboration. Even so, I find that a wiki works amazingly well for the kind of quick changes I make on a regular basis.

The one problem I have is that anything sensitive (ie. passwords) is stored outside the Wiki in more secure storage, but it would be nice to have it more immediately available.

Answer 34

Documenta-what ? Wee don't neeed no steenking doocumentation !

It's probably an awful practice, but it's alas par with the course in most IT Organization. No time, no budget, no want to write.