[OPEN-ILS-DOCUMENTATION] wikis and documentation formats [Was: ACQ and Reporting documentation]

[Dan Scott]

2008/8/11 Karen G. Schneider <kgs at esilibrary.com>:
> 3) Wiki format -- I like the medium, and it's a great vehicle for end-user
> contributions - it's all good. But I'm unsure of is how well our needs could
> be met from user contibutions vs. any "official" professional tech writer
> created documentation.
>
> -----------
>
> To clarify, I don't mean user-generated documentation should replace
> "official" documentation--although we may want expert users to be able to
> contribute to the project (perhaps not as formally as the coding "commit"
> process works, but with some oversight). I'm talking about publication
> platform -- that is, using the wikis as the home base for documentation
> editing -- which is actually true for most (but not all) of the existing
> documentation anyway. I say this in part because behind scenes I've been
> industriously crafting suggested revisions to older material and some new
> material (FAQs and whatnot), and as far as end-user material goes, the stuff
> that's not locked up in static web pages is much easier to modify -- and for
> that matter, read. I have a hunch not many people print out the 1,913-page
> PostgreSQL manual... but I bet quite a few people search its webbier (and no
> less formal) counterpart.

Eh... I'm passionate about documentation, so I apologize if the tone
here is strident, but I can't resist making a few points on this:

1. Yes, the wiki is currently the home for most of the existing
documentation. But I think that's because there has been no other
realistic option. We don't have dedicated writers creating stable
documentation in concert with development, and we're mostly playing
catch-up with the developers. I think that's a fine short term
solution, given the quantity of resources we have at hand, and until
we have a critical mass of content I'm contributing documentation to
the wiki rather than pouring it into DocBook - but in the long run, I
hope that we can attract (or fund) dedicated writers.

2. Static sets of documentation can be both bad and good.
Documentation that is out of date or doesn't exist because it's too
hard to change is definitely bad. On the other hand, if you are
running Evergreen 1.2.2.4, you're going to want to be able to read
about how to change circulation rules / organization unit hierarchies
in your version of Evergreen - not the cool Conify administration
interface that was only introduced in 1.4.0. Notice that with
PostgreSQL, you can select snapshots of the documentation
corresponding to major x.y versions
(http://www.postgresql.org/docs/manuals/). This is hard to pull off
with a wiki.

3. There may not be many people printing out the 1,913 page manual,
but I can guarantee that there are a lot of people who have downloaded
the PDF and carry it around with them in one convenient, searchable,
well-organized format.

4. Wikis are pretty darned awkward to translate. Dokuwiki offers some
support for translation, but it's quite limited.

5. Despite the ease of modification, wikis are pretty hard to edit.
Trying to make terminology, style, and structure consistent across a
set of wiki pages isn't a whole lot of fun. It's not fun in something
like DocBook either, but at least you can easily make global changes,
and the PDF format lets you edit across a ton of pages rather than
clicking through pages.

I'm not opposed to using the wiki as the de facto
documentation-editing platform, or as a short term publishing
platform. At this point, anything that lets us increase our volume and
quality of documentation, even in just one language, is goodness.

Long-term, however, there are a lot of advantages to using something
else as the official documentation-publishing platform (with my bias
obviously being towards DocBook).

-- 
Dan Scott
Laurentian University