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
![Page 1: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/1.jpg)
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
![Page 2: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/2.jpg)
Goals for this talk
•Describe where we are now•Describe single-source documentation•Lay groundwork for discussion (hopefully
leading toward decisions)
![Page 3: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/3.jpg)
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
![Page 4: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/4.jpg)
![Page 5: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/5.jpg)
![Page 6: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/6.jpg)
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)
![Page 7: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/7.jpg)
Documentation challenges
•Not integrated into development or tied into releases
•No clear community-chosen toolset •Lack of committed resources •No intentional production process
![Page 8: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/8.jpg)
Current Evergreen documentation formats: The 3 Ws
•Wiki — the Dokuwiki instance•Word — word processing documents •Whatever — random formats for movies,
audio, etc.
![Page 9: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/9.jpg)
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
![Page 10: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/10.jpg)
Resources and Opportunities
•Growing perception of need•Critical mass •Good communication tools▫Discussion list▫GoToMeeting▫Evergreen blog
•Areas of in-house expertise
![Page 11: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/11.jpg)
Evergreen Documentation Project Has Very Basic Needs…
•Some People•A Plan•And a Pickaxe
![Page 12: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/12.jpg)
People: Evergreen community members interested in…
•Documentation production (writing)•Documentation project planning*•Documentation project management*
* These are new to the Evergreen documentation project
![Page 13: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/13.jpg)
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
![Page 14: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/14.jpg)
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
![Page 15: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/15.jpg)
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
![Page 16: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/16.jpg)
High-level guidance
•Format•Style•Valid content•Location•Frequency•How to contribute•Tool usage
![Page 17: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/17.jpg)
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
![Page 18: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/18.jpg)
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
![Page 19: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/19.jpg)
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
![Page 20: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/20.jpg)
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
![Page 21: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/21.jpg)
![Page 22: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/22.jpg)
![Page 23: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/23.jpg)
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.
![Page 24: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/24.jpg)
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
![Page 25: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/25.jpg)
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
![Page 26: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/26.jpg)
Single-source Approaches
•DocBook•DITA•Homespun variations (e.g. php.net)
•…All of these are based on XML.
![Page 27: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/27.jpg)
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
![Page 28: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/28.jpg)
XSL — Extensible Stylesheets:
•Specify how XML will be transformed into various formats (HTML, PDF, e-print)
•Part of the W3C’s “XML Activity”
![Page 29: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/29.jpg)
Relax, Don’t Worry, Have Some XML
•Beersmith demo
•DocBook demo
![Page 30: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/30.jpg)
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
![Page 31: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/31.jpg)
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
![Page 32: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/32.jpg)
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.
![Page 33: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/33.jpg)
Getting to PDF (or other print formats)
XML File
DocBook Stylesheet
XSLTProcessor
FO File
FOProcessor
PDF/Print
![Page 34: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/34.jpg)
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
![Page 35: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/35.jpg)
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)
![Page 36: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/36.jpg)
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
![Page 37: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/37.jpg)
Essential DocBook Resources
•Web: Docbook.org•Email list: Docbook-apps •Book: Norman Walsh, DocBook: The Definitive Guide•Book: Robert Stayton, DocBook XSL, 4th Edition
![Page 38: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/38.jpg)
Significant OSS DocBook Implementations
• Linux •Fedora •PostgreSQL •PHP•TortoiseSVN•Subversion•FreeBSD •Gnome
![Page 39: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/39.jpg)
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
![Page 40: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/40.jpg)
Resources for Documentation
•Community participation•In-kind production•Commercial investment•Funded production
![Page 41: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/41.jpg)
DocBook Demo….
![Page 42: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/42.jpg)
Final thoughts
![Page 43: Evergreen Docs Planning Session 2009](https://reader033.vdocuments.net/reader033/viewer/2022052821/5549b380b4c90564768b4921/html5/thumbnails/43.jpg)
Thanks!•Karen G. Schneider
•Equinox: http://www.esilibrary.com•Evergreen: http://www.evergreen-ils.org