evergreen docs planning session 2009
DESCRIPTION
Slides used in a 3-hour planning session for project-wide documentation coordination at Evergreen International Conference 2009.TRANSCRIPT
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
•Equinox: http://www.esilibrary.com•Evergreen: http://www.evergreen-ils.org