Last night, Ragan Haggard of Sun Microsystems told STC Austin about his journey producing documentation for OpenDS (an open source product) using only wikis. From the myriad available, they picked a wiki -- JSPwiki
-- that met their key requirements (still in active development ,
syntax, rich text, content control); however, not even the
best-in-class commercial wiki, Confluence,
could offer the Section 508 (accessibility) and commercial quality PDF
book output they still need. (He hadn't heard of FLOSS manuals,
although that's still not the holy grail.)
Their open source documentation site is OpenDS.org/wiki; the team consists of 3 writers and 1 manager, along with Sun SME contributors. Text formatting in JSPwiki is done in wikitext, which is a simple (well, simpler than HTML) text markup for creating structured formatting (see the Rules for text formatting,
to get an idea). Wikitext limitations, such as in creating complex list
structures, were one of the downsides of using JSPwiki; other problems
were the painfulness of renaming pages and the lack of email pings for
changed pages. About their processes:
- New articles are generally written and reviewed before being added to the live wiki.
- The Recent changes page is most helpful for wiki administration (not users), to scan for spam.
- Product versioning is "snapshot and freeze": at release time, they
copy and lock the wiki at that version number (lock to users: Sun folks
can still update).
- To get the conditional print output they need, they're working out a DocBook export and development process.
- Sun-branded wikis are Confluence-based: wikis.sun.com
Promising! While I couldn't get a good sense of
how their product versioning strategy could work for a product like
ours (the company working on the future release's wiki while the user
community is adding content to the current releases' wikis, and how to
synchronize across them?), I think it could work for wiki-based
documentation development that occurs
within the company only
(which in fact is what the OpenDS folks were doing: no significant
non-Sun participation). The wikis (one per major point release) would
be the single source for non-HTML outputs and themselves be the HTML
output for released versions; the future-facing wiki would be hidden
from users until release time. This way, Support, Consulting, Training
-- everyone -- could make fixes and improvements in real time across
the comprehensive product doc set (admittedly, some fixes would need to
be made in multiple wikis). The one thing that's missing -- and it's
huge -- is a
wikislicing
solution that allows for remixing and reuse across these wikis, and
with lovely print publications (full front and back matter) at the end
of it.
Ragan said that the biggest reason the wiki fad will endure is the
huge leap in quality brought by collaborative authoring: More eyes,
more brains, more hands, more useful content. I think he's spot on,
there. It's more when than if, I think, just waiting for toolset
maturity.
