SUMMARY: how do you manage documentation?

From: John Christian <>
Date: Fri Mar 04 2005 - 11:48:54 EST

Thank you for all of the expert opinions! All of the suggestions look like
excellent applications. All of them could probably be adapted to our needs
with varying degrees of effort. My focus is on finding something that provides
most of what we need with the least amount of installation, configuration, and
customization effort.


Tom Grassia       FAQ-O-Matic

Carl Ma           MS-SharePoint

Andrew Hall       Docbook

Anothony D'Atri   RCS a webtree

NO UCE            Owl

Alan Pae
<>  (then drill down)

Ric Anderson      DokuWiki

VEGH Karoly       Wikipedia

David Talkington  TWiki

Clive McAdam      wiki

Lars Hecking      Apache module mod_dav, DAVexplorer

Tim Chipman       myDms


Based on our specific needs, list feedback, and what we've read so far, the
front runners *at this point* are Owl, OpenCMS, and Wiki-derived. All
suggestions received are outlined farther below.


Pros: existing docs can remain in native format, user logins, version control

Cons: need to setup MySQL or Postgresql

OpenCMS <>

Pros: existing docs can remain in native format, WYSIWIG input, familiar
Explorer-style viewing, per-project/topic input forms

Cons: WYSIWIG support in IE only, need to setup search engine

MediaWiki, DokuWiki, TikiWiki <>

Pros: Popular tool with many add-ons, widely used for content management, it's
fun to say "wiki wiki wiki"

Cons: overwhelming, may have too many features and add-ons, PHB's may need to
learn formatting syntax, not sure is it can manage legacy docs.

BTW: My favorite response from [an anonymous writer] shared the following
insights: "I don't create documentation for others to use. I put everything on
a personal apache webserver that runs out of my home dir. So when I'm fired
and 'userdel -r username' hits me, all evidence of my presence is obliterated.
They can hire me back as a consultant when they want to know how it works."
Yes, they were joking.


Most people agreed that a central folder with subfolders will sprawl and
become unmanageable. The infamous intranet site will never get updated if
people are expected to manually update static html pages. Converting all
information to [SGML | XML | SML | other] sounds neat and provides great
publishing options. Probably works great if starting fresh, but converting
existing assets can be time consuming. Others echoed my concerns that PHBs
just aren't going to learn the markups.

Obviously, there's a problem with legacy documentation stuck in Word, Excel,
Visio, and other proprietary formats. Integrating these assets into a DMS/CMS
is inherently difficult. As one of the list members gently suggested: "MS-word
.docs are a blight on the flesh of humanity."  Here's a weblog that captures
the essence of why Word docs suck for collaboration:

Additional resources I found included: <>  CMS reviews, summaries,
and more. They suggest there are over 1000 products that claim to manage
web-accessible content. I believe it! They focus on the top 40. No necessarily
the best 40, but the most significant players. Focused on commercial products,
but does have an open source section. <>  List of open
source content management systems. Not an exhaustive list, but a good place to
get ideas.

BTW: Alan Pae's site (
<> ) has an enormous list of tools in some
way related to the Solaris world organized by categories. I'll definitely be
going back to this site for the wealth of other links. The documentation tools
listed (that I found) seemed to be more focused on collecting highly technical
system information. These might be great for feeding into the DMS we envision,
but don't seem likely to support our overall needs for general content

Below are the other tools suggested by list members. Please note: Any
pros/cons are based on a cursory inspection of the tool's web site with a
focus on the needs of our specific environment.


Pros: mature, easy to add text content, small/quick/easy to deploy

Cons: input is text centric; therefore, doesn't consume proprietary files

Docbook <>

Pros: geared towards technical documentation, O'Reilly uses it, generates
documentation in multiple styles

Cons: Existing docs must be converted to SGML or XML, doesn't consume
proprietary files


Pros: claims to have many of the features we need

Cons: looks like a 1 guy development team, can it consume proprietary docs?

Track web content with RCS

Pros: RCS is already used at this site for code management

Cons: doesn't consume proprietary files

Apache module mod_dav, DAVexplorer <>

Pros: attractive to engineers managing web content

Cons: appears immature, last release was 2001, may require extensive

Sun's Configuration and Service Tracker

Pros: Continuous tracking of h/w and s/w events on Solaris hosts, historical
data automatically maintained, could be used to feed our DMS

Cons: no provision for manually created documents

Borland's StarTeam <>

Pros: I'm familiar with it, robust, enterprise level

Cons: probably overkill for our needs, not free

MS-SharePoint <>

Pros: Integrates into MS environments, user-customizable portals,

Cons: no MS-Windows servers at this site, not free

Matrix One PDM <>

Pros: robust, enterprise level, pretty marketing PDFs

Cons: probably overkill for our needs, not free, too many buzzwords


-John Christian


I'm looking for suggestions on a centralized documentation management system

that would be shared by a team of 5 sysadmins and a few PHB's. There are some

similar threads in the archives, but they're a few years old. I'm interested

in the latest trends used by list members and their experience with actually

using a particular tool/approach over time.

The documents would include server build recipes, backup/restore procedures,

inventory spreadsheets, meeting notes, good PDF's, outage calendar, and other

documentation related to the IT department. The documentation that currently

exists includes files such as Word, Excel, Visio, txt files, e-mails, and

more. We would like to have a central repository that includes most of the

following features:

runs on a 'nix

browser accessible


login password

revision control

easy to upload new content

menus self update with new content

We've considered:

a shared folder with topical subfolders (too much dir sprawl, no revision


internal web server (updating html code and FTPing new docs sucks for PHBs)



convert everything to XML (cool, but probably not gonna happen)

Borland StarTeam (spend money on s/w instead of beer? yuck!)

Pros, cons, and any suggestions are very welcome. Will summarize.
sunmanagers mailing list
Received on Fri Mar 4 11:54:10 2005

This archive was generated by hypermail 2.1.8 : Thu Mar 03 2016 - 06:43:44 EST