evergreen docs planning session 2009

Some People, A Plan, and a Pickaxe:The Evergreen Documentation Project

Karen G. SchneiderCommunity LibrarianEquinox Software, Inc. “The Evergreen Experts”http://esilibrary.com May, 2009

Goals for this talk

•Describe where we are now•Describe single-source documentation•Lay groundwork for discussion (hopefully

leading toward decisions)

Evergreen documentation (Current)

•Some technical documentation generated during development processes

•Some legacy materials from PINES roll-out •An increasing quantity of community-

generated end-user documentation

Previous EG documentation activities

•Mailing list (ongoing)•Training sessions (early on)•A proposal (Sep 07)•Another proposal (Jan 09)•Conifer intern (Jan – Apr 09)•A response (May 09)

Documentation challenges

•Not integrated into development or tied into releases

•No clear community-chosen toolset •Lack of committed resources •No intentional production process

Current Evergreen documentation formats: The 3 Ws

•Wiki — the Dokuwiki instance•Word — word processing documents •Whatever — random formats for movies,

audio, etc.

Unintended consequences…

•Software knowledge locked in developers’ brain trust

•Poor first impression for the project•Much time wasted asking basic questions•Much time wasted answering basic questions

Resources and Opportunities

•Growing perception of need•Critical mass •Good communication tools▫Discussion list▫GoToMeeting▫Evergreen blog

•Areas of in-house expertise

Evergreen Documentation Project Has Very Basic Needs…

•Some People•A Plan•And a Pickaxe

People: Evergreen community members interested in…

•Documentation production (writing)•Documentation project planning*•Documentation project management*

* These are new to the Evergreen documentation project

Possible organizational model

• Exec committee…▫ High-level decisions▫ Interface with community leaders, vendors, etc.

• Steering committee…▫ Organizes activities around releases, gaps in

documentation, or other needs (e.g. FAQs, stylesheets)▫ Establishes and maintains guidelines for format and

workflow▫ Helps establish and maintain functional workspace▫ Recruits new team members

• Implementation team…▫ Produces, edits, tests, and updates content and associated

materials

A Plan… Suggestions have included:

•Functional cross-project workgroup(s) for documentation▫Possibly tiered (Exec, Steering,

Implementors)•“Docs document” for project goals and

organization•Timeline with milestones•Regular… dare we say it… meetings

Possible documentation tasks

•Project leadership — macro and micro (more on the next slide)

•Drafting documentation•Converting docs to the agreed-on format•Editing•Testing •Policing•Creating and maintaining the aesthetic presence

High-level guidance

•Format•Style•Valid content•Location•Frequency•How to contribute•Tool usage

Possible documentation workflow

•Writer…▫Creates or edits a chunk of documentation

•Field Editor…▫Converts to DocBook as needed▫Uploads document to svn repository

Located relative to release: e.g. rel_1_6, trunk, rel_2•Editor in Chief…

▫Reviews file▫Transforms to HTML/PDF ▫Moves file(s) to website

A Pickaxe, Part 1

•One unifying documentation-production toolset scaled to the needs of the Evergreen project

•A single site where all documentation is gathered

•Communication tools•Production tools

A Pickaxe, Part 2: Production Plan Pointers

•Style guide▫Focused on markup and structure, not

appearance•Sampler

▫Featuring all approved markup examples•Template Files

▫Heavily annotated empty versions of documents

A Pickaxe, Part 3:Yet More Recommendations•Best Practices Wiki

▫Lots of documentation snippets presented side-by-side with examples

▫Tools guidance▫Carefully documented workflow▫Participants listed very clearly

•Mailing list▫We have that, anyway!

•Training sessions▫Webinars would work well

Reality Check

•Tools can be easy or hard… but the truly challenging part of a documentation project is organizing and managing the labor effort behind the writing.

Toolset functional recommendations…

•Cross-platform•Single-source, reusable content•Support for distributed authoring•Supports translation•Standards-based•Well-established user community•Availability of publishing tools•Ease of use

Single-Source Publishing:One Spirit, Many Gifts

•Same source produces print, PDF, HTML, help files

•Can tie source to versions•Lends itself to translations•Central control for look/feel/style•Good for distributed labor efforts

Single-source Approaches

•DocBook•DITA•Homespun variations (e.g. php.net)

•…All of these are based on XML.

XML — Extensible Markup Language

•Part of the W3C’s “XML Activity”▫Over a dozen W3C working groups

•Simple, flexible text format•A decade of rapidly-growing international

support•Increasingly the de facto markup language

XSL — Extensible Stylesheets:

•Specify how XML will be transformed into various formats (HTML, PDF, e-print)

•Part of the W3C’s “XML Activity”

Relax, Don’t Worry, Have Some XML

•Beersmith demo

•DocBook demo

DocBook

•OASIS standard•XML schema (As of 5.0, RelaxNG, not

DTDs)•Easier ramp-up than DITA•Designed for technical documentation•Some “Evergreen expertise” with it

Possible DocBook Workflow

•Documentation is written in or converted to DocBook XML

•Writers “check in” their work to a repository•Editors review and edit XML so it is valid and well-

formed•Designers create CSS•Editors select XSL stylesheets •Editors transform XML to HTML or other formats with

an XSL processor•Editors upload HTML (and any associated images) to a

website

Getting to HTML

DocBook XML File*

DocBook Stylesheet

XSLTProcessor

HTML Files

*May also include CSS and a Makefile

Most writers will only see

and work with these XML files.

Getting to PDF (or other print formats)

XML File

DocBook Stylesheet

XSLTProcessor

FO File

FOProcessor

PDF/Print

Common DocBook Tools

•DocBook-aware XML editor — XMLMind, Eclipse (free); oXygen, $

•XSL stylesheets (free, nice selection of default sheets on docbook.org)

•XSL and FO processors — free ones are good▫ See xsltproc, Saxon, FOP▫ One or several built-in to commercial editors

•Web design tools — for creating CSS to style the plain-jane DocBook HTML

•Repository — for check-in, version control, release tagging, project oversight

Typical DocBook version control model

Documents checked in: •DocBook XML•Transformation script or Makefile used to build the

output▫Best practice: include info about your tool chain (e.g.

switches, FOP version, etc.)•CSS files•Associated resources—e.g. icons for admonitions and

callout images•Any edited XSLT (though possibly placed in another

repo)

No-cost DocBook HTML Production (Windows users)

•Create DocBook XML in XMLMind, text editor, or some other tool

•Validate XML with xmllint validation tool•Select XSL (use default pages or create/edit XSL)•Write (or borrow) CSS file to “pretty up” pages•Write batch file in xsltproc to process XML, CSS, and

any associated images or media▫Automates processing▫Documents the toolchain process

•Upload HTML and images to website

Essential DocBook Resources

•Web: Docbook.org•Email list: Docbook-apps •Book: Norman Walsh, DocBook: The Definitive Guide•Book: Robert Stayton, DocBook XSL, 4th Edition

Significant OSS DocBook Implementations

• Linux •Fedora •PostgreSQL •PHP•TortoiseSVN•Subversion•FreeBSD •Gnome

DocBook Reality Check

•XML learning curve — nontrivial to produce good documentation

•Tools are either arcane, unsatisfactory, or not free

•Valid, well-formed XML output is only 80% of the battle — plain DocBook HTML still requires styling

Resources for Documentation

•Community participation•In-kind production•Commercial investment•Funded production

DocBook Demo….

Final thoughts

Thanks!•Karen G. Schneider

kgs@esilibrary.com1-877-OPEN-ILS

•Equinox: http://www.esilibrary.com•Evergreen: http://www.evergreen-ils.org