SUMMARY: how do you manage documentation?

From: John Christian (john.christian_at_TheCReGroup.com)
Date: 03/04/05

  • Next message: Eric Seale: "SUMMARY: solaris 10 on the V20z" 
    Date: Fri, 4 Mar 2005 11:48:54 -0500
To: <sunmanagers@sunmanagers.org>

    Sunmanagers,

    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.

    THANKS TO:

    Tom Grassia FAQ-O-Matic

    Carl Ma MS-SharePoint

    Andrew Hall Docbook

    Anothony D'Atri RCS a webtree

    NO UCE Owl

    Alan Pae http://alanpae.tripod.com/index.htm
    <http://alanpae.tripod.com/index.htm> (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

    BRIEF SUMMARY:

    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.

    Owl

    http://sourceforge.net/projects/owl/
    <http://webmail.thecregroup.com/exchweb/bin/redir.asp?URL=http://sourceforge.
    net/projects/owl/>

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

    Cons: need to setup MySQL or Postgresql

    OpenCMS

    http://www.opencms.org/opencms/en/ <http://www.opencms.org/opencms/en/>

    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

    http://wikipedia.sourceforge.net/ <http://wikipedia.sourceforge.net/>

    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.

    ADDITIONAL SUMMARY:

    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:
    http://www.oreillynet.com/pub/wlg/3793
    <http://www.oreillynet.com/pub/wlg/3793>

    Additional resources I found included:

    http://www.cmswatch.com <http://www.cmswatch.com/> 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.

    http://www.la-grange.net/cms <http://www.la-grange.net/cms> List of open
    source content management systems. Not an exhaustive list, but a good place to
    get ideas.

    BTW: Alan Pae's site (http://alanpae.tripod.com/index.htm
    <http://alanpae.tripod.com/index.htm> ) 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
    management.

    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.

    FAQ-o-matic

    http://faqomatic.sourceforge.net/fom-serve/cache/1.html
    <http://faqomatic.sourceforge.net/fom-serve/cache/1.html>

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

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

    Docbook

    http://www.docbook.org/ <http://www.docbook.org/>

    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

    myDms

    http://dms.markuswestphal.de/about.html
    <http://dms.markuswestphal.de/about.html>

    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

    http://www.gnu.org/software/rcs/rcs.html
    <http://www.gnu.org/software/rcs/rcs.html>

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

    Cons: doesn't consume proprietary files

    Apache module mod_dav, DAVexplorer

    http://www.webdav.org/ <http://www.webdav.org/>

    Pros: attractive to engineers managing web content

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

    Sun's Configuration and Service Tracker

    http://www.sun.com/download/products.xml?id=3fcdb0dd
    <http://www.sun.com/download/products.xml?id=3fcdb0dd>

    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

    http://www.borland.com/starteam/ <http://www.borland.com/starteam/>

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

    Cons: probably overkill for our needs, not free

    MS-SharePoint

    http://www.microsoft.com/sharepoint/ <http://www.microsoft.com/sharepoint/>

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

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

    Matrix One PDM

    http://www.matrixone.com/ <http://www.matrixone.com/>

    Pros: robust, enterprise level, pretty marketing PDFs

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

    HTH,

    -John Christian

    ORIGINAL POST

    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

    searchable

    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

    control)

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

    TikiWiki

    OpenCms

    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
    sunmanagers@sunmanagers.org
    http://www.sunmanagers.org/mailman/listinfo/sunmanagers

  • Next message: Eric Seale: "SUMMARY: solaris 10 on the V20z"