evergreen documentation lightning talk
DESCRIPTION
A five-minute description of the forward path for documentation for Evergreen open source library software. (There is a much longer version of this talk that will also be uploaded.)TRANSCRIPT
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!