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

[Karen G. Schneider]

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

Good point!
> 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.
>   

Ah yes, I was displaying my English-language bias.
> 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.
>   

Well, I am completely with you on the editorial limitations of wikis. I 
have problems both with composing and editing in wikis (learning a 
bespoke formatting language, being frustrated by simple formatting 
limitations, and my greatest peeve, doing all of my editing in a 
composition window the size of two credit cards laid side by side--it's 
like the word processors we were using in the 1970s) and with the UX 
issues -- just to start with, the the default page has no left-right 
constraints; I get a neck crick just reading my own writing. Plus the 
design sense of the typical wiki format, unless CSS-ified by skilled 
hands, feels, I don't know... pre-Glasnost Russia.

In wiki editing, I spend too much time thinking about the mechanics of 
writing versus actually writing, and I imagine any highly-formatted 
composition is arduous to create and maintain (and as you point out, 
internationalize--which is not just a cross-border issue; to look at 
just one language, 7% of Georgia's population is Hispanic, and Georgia, 
with its agriculture, is now one of the top six states to attract 
migrant workers from Mexico, whose first language is of course Spanish. 
I pass many Spanish-language-only businesses as I drive around Georgia; 
if you're ever in Omega, I recommend lunch at Taqueria Jesus y Maria).
> 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).
>   
A professional tech-documentation platform sounds like an excellent 
North Star, and I am glad you raised that point. Down here on the bottom 
of Maslow's hierarchy, it's a big step up to move from hardwired web 
pages last updated in Evergreen's alpha era to the relative access and 
flexibility of wikis (and it's a big step up to have the luxury of time 
to attend to these pages at all--even stuff as basic as FAQs). But you 
argue persuasively that's at best a pit stop, not where we want the bulk 
of our formal documentation to stay.

You had written, "We don't have dedicated writers creating stable 
documentation in concert with development, and we're mostly playing 
catch-up with the developers." This is absolutely correct (and was the 
point of a blog post I wrote y'day that I just went live with: 
http://esilibrary.com/blog/?p=73 ). We should be thinking in terms of 
how we move documentation to the next level--and keep it there--which 
means in part building documentation into the development process and 
sustainability model.

(It now strikes me that some of the people approaching Evergreen's 
community about documentation work may have expectations about tools... 
and we may need to have answers... and the answers should be 
consistent... and forward-looking... ok, thanks a lot, Dan, one more 
thing to worry about ;> )

-- 
| Karen G. Schneider
| Community Librarian
| Equinox Software Inc. "The Evergreen Experts"
| Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
| E-Mail/AIM: kgs at esilibrary.com
| Web: http://www.esilibrary.com