evergreen documentation lightning talk

The Problem, Some People, A Plan, and a Pickaxe:A Report-Out from the May 20, 2009 Documentation DiscussionEvergreen 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

DocBook XML File*

DocBook Stylesheet

XSLTProcessor

HTML Files

*May also include CSS and a Makefile

Most writers will only see

and work with these

files.

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!