Docbooks/documentation workshop

[Karen Schneider <kgschneider@gmail.com>]

Back in early February I asked for examples for a Docbook workshop.
I'm actually still planning a workshop for a conference next month.
However, after speaking with various stakeholders, observing people
learning and working with Docbook, and following discussions on this
list, my objectives have evolved. Thought you all might be interested
to see where this is headed.

Instead of a "why Docbook" workshop, I'm planning to facilitate a
half-day, high-level discussion of "why and how documentation," with a
chunk of time devoted to single-source documentation, and Docbook in
particular. I will demo Docbook and discuss its strengths and also its
challenges, and compare it to other approaches to documentation. You
could call this "pro Docbook, with caveats."

A very preliminary outline follows (input welcome):

1. Documentation: what is it and why bother?

-- What it is and what it isn't

-- Adding value to Evergreen

-- "Early testing" benefits

-- Breadcrumbs to decisions

-- A pathway out of RFP hell?

2. Documentation: form and function

-- Developers are from Mars, librarians are from Venus: two distinct
documentation communities in Evergreen

    -- implications for designing a documentation project for Evergreen

-- The three W's of current Evergreen documentation: Wiki, Word, and Whatever

     -- advantages and disadvantages of all three approaches

-- Single-source documentation

    -- This Bud's on me: the possibilities of single-source
documentation (using BeerXML example)

    -- Docbook: a common documentation schema

        -- How it works (show EG examples)

    -- Evergreen and Docbook: the pluses and minuses

        -- Pull together EG documentation under one roof in a
single-source format

        -- No silver bullet, no easy roundtripping from existing formats

3. Documentation: how do we get there?

-- Building dev documentation into the Evergreen development workflow

-- Building user documentation into the Evergreen project experience

-- Tools, time, and talent

-- Next steps


Thanks again to everyone who contributed to the earlier discussion...
that was a terrific help!

-- 
-- 
| Karen G. Schneider
| Community Librarian
| Equinox Software Inc. "The Evergreen Experts"
| Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
| kgs@esilibrary.com
| Web: http://www.esilibrary.com
| Be a part of the Evergreen International Conference, May 20-22, 2009!
| http://www.lyrasis.org/evergreen