Evergreen Docs Planning Session 2009

Evergreen Docs Planning Session 2009 - Presentation Transcript

Some People, A Plan, and a Pickaxe: The Evergreen Documentation Project Karen G. Schneider Community Librarian Equinox 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 Most writers will only see and work with these XML files. DocBook XML File* XSLT HTML Files Processor DocBook Stylesheet *May also include CSS and a Makefile

Getting to PDF (or other print formats) XML File XSLT FO File Processor DocBook Stylesheet FO PDF/Print Processor

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.com 1-877-OPEN-ILS • Equinox: http://www.esilibrary.com • Evergreen: http://www.evergreen-ils.org