Evergreen Documentation Lightning Talk

The Problem, Some People, A Plan, and a Pickaxe: A Report-Out from the May 20, 2009 Documentation Discussion Evergreen International Conference 2009 Karen G. Schneider, Equinox Software & Paul Weiss, Sage Library System

The Problem…

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 ▫ Often duplicating/overlapping existing efforts and located here, there, everywhere

Core docs problems • Not integrated into development or tied into releases • Fuzziness between “core” and “community” docs • No clear, community-chosen toolset • Lack of committed resources • No intentional production process • No identified leadership

We’re an open source STEREOTYPE!!!!

Current Formats: The 3 Ws • Wiki — the Dokuwiki instance • Word — word processing documents • Whatever — PDF, text, random formats for movies, audio, etc.

With every additional format, another kitten dies.

And not the best of first impressions!

Other unintended consequences… • Software knowledge locked in developers’ brain trust • Much time wasted asking basic questions • Much time wasted answering basic questions • No unified, well-organized, “one voice” presence

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)

Resources and Opportunities • Growing perception of need • Critical mass • Good communication tools • Areas of in-house expertise • Wide assistance/input from other FOSS projects

The People…

Meet the DIGGERS! (Documentation Implementation Group) • Approx. 20 people met 5/20/09 • Committed to building a docs project • Will meet every other week • Karen Schneider and Paul Weiss, project coordinators

The Plan…

DIGGER Recommendations • A single-source, open, standards-based format for core Evergreen documentation • DocBook XML as the core authoring format • Any format (Word, Wiki, Whatever) for initial documentation contributions

Can you DIG it? There’s a role, big or small, for everyone… • Documentation production (writing, editing, design, testing, CSS design, infrastructure help, etc.) • Documentation project planning • Documentation project management

The Pickaxe…

Toolset “highly desirables” • Cross-platform • Single-source, reusable content • Support for distributed, modular authoring • Facilitates translation • Standards-based • Well-established user community • Widely available fee-or-free publishing tools

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

DocBook • OASIS standard • XML schema (As of 5.0, RelaxNG, not DTDs) • Friendly, responsive user community • Designed for technical documentation • Some “Evergreen expertise” with it • Good mix of “fee or free” tools available

Significant OSS DocBook Implementations • Linux • Fedora • PostgreSQL • PHP • TortoiseSVN • Subversion • FreeBSD • Gnome

Getting to HTML Most writers will only see and work with these files. DocBook XML File* XSLT HTML Files Processor DocBook Stylesheet *May also include CSS and a Makefile

Common DocBook Toolset • DocBook-aware XML editors— 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 • Web design tools — for creating CSS • Repository — for check-in, version control, release tagging, project oversight • Website – capable of supporting desired functionality

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

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

DIGGER Group Commitments • Single-source documentation • DocBook format • Accept content “by any means necessary”

DIGGER Startup Activities • Promote the existence of DIGGERS • Carve out roles • Develop process plan • Create style guide • Address IP issues • Build a DocBook “proof of concept” page linking out to community documentation • Provide samples, checklists, and heavily-annotated templates

Think of the kittens. Help the DIGGER Project!

Evergreen Documentation Lightning Talk

by Evergreen ILS

Accessibility

Categories

Upload Details

Usage Rights

Statistics

Evergreen Documentation Lightning Talk Presentation Transcript