Some People, A Plan, and a Pickaxe:
The Evergreen Documentation Project

Karen G. Schneider
Community Librarian
Equinox So...
Goals for this talk


• Describe where we are now
• Describe single-source documentation
• Lay groundwork for discussion (...
Evergreen documentation (Current)


• Some technical documentation generated
  during development processes
• Some legacy ...
Previous EG documentation activities

      • Mailing list (ongoing)
      • Training sessions (early on)
      • A propos...
Documentation challenges

• Not integrated into development or tied
  into releases
• No clear community-chosen toolset
• ...
Current Evergreen documentation formats:
The 3 Ws

• Wiki — the Dokuwiki instance
• Word — word processing documents
• Wha...
Unintended consequences…

• Software knowledge locked in developers’ brain
  trust
• Poor first impression for the project...
Resources and Opportunities

 • Growing perception of need
 • Critical mass
 • Good communication tools
   ▫ Discussion li...
Evergreen Documentation Project Has Very
Basic Needs…


            • Some People
            • A Plan
            • And a...
People: Evergreen community members
interested in…


• Documentation production (writing)
• Documentation project planning...
Possible organizational model

 • Exec committee…
   ▫ High-level decisions
   ▫ Interface with community leaders, vendors...
A Plan… Suggestions have included:

• Functional cross-project workgroup(s) for
  documentation
  ▫ Possibly tiered (Exec,...
Possible documentation tasks
• Project leadership — macro and micro (more on
  the next slide)
• Drafting documentation
• ...
High-level guidance

            • Format
            • Style
            • Valid content
            • Location
         ...
Possible documentation workflow
• Writer…
 ▫ Creates or edits a chunk of documentation
• Field Editor…
 ▫ Converts to DocB...
A Pickaxe, Part 1

• One unifying documentation-production
  toolset scaled to the needs of the
  Evergreen project
• A si...
A Pickaxe, Part 2: Production Plan Pointers

• Style guide
  ▫ Focused on markup and structure, not
    appearance
• Sampl...
A Pickaxe, Part 3:
Yet More Recommendations
• Best Practices Wiki
  ▫ Lots of documentation snippets presented side-
    b...
Reality Check


• Tools can be easy or hard… but the truly
  challenging part of a documentation
  project is organizing a...
Toolset functional recommendations…

• Cross-platform
• Single-source, reusable content
• Support for distributed authorin...
Single-Source Publishing:
One Spirit, Many Gifts

• Same source produces print, PDF, HTML,
  help files
• Can tie source t...
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, flexib...
XSL — Extensible Stylesheets:


• Specify how XML will be transformed into
  various formats (HTML, PDF, e-print)
• Part o...
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 technic...
Possible DocBook Workflow

• Documentation is written in or converted to DocBook
  XML
• Writers “check in” their work to ...
Getting to HTML                            Most writers will
                                             only see and
   ...
Getting to PDF (or other print formats)


     XML File


                       XSLT        FO File
                     ...
Common DocBook Tools
• DocBook-aware XML editor — XMLMind, Eclipse
  (free); oXygen, $
• XSL stylesheets (free, nice selec...
Typical DocBook version control model

Documents checked in:
• DocBook XML
• Transformation script or Makefile used to bui...
No-cost DocBook HTML Production
(Windows users)
• Create DocBook XML in XMLMind, text editor, or some
  other tool
• Valid...
Essential DocBook Resources


•   Web: Docbook.org
•   Email list: Docbook-apps
•   Book: Norman Walsh, DocBook: The Defin...
Significant OSS DocBook Implementations
              •   Linux
              •   Fedora
              •   PostgreSQL
    ...
DocBook Reality Check

• XML learning curve — nontrivial to
  produce good documentation
• Tools are either arcane, unsati...
Resources for Documentation


     • Community participation
     • In-kind production
     • Commercial investment
     •...
DocBook Demo….
Final thoughts
Thanks!
• Karen G. Schneider
 kgs@esilibrary.com
 1-877-OPEN-ILS

• Equinox: http://www.esilibrary.com
• Evergreen: http:/...
Evergreen Docs Planning Session 2009
Evergreen Docs Planning Session 2009
Evergreen Docs Planning Session 2009
Evergreen Docs Planning Session 2009
Upcoming SlideShare
Loading in …5
×

Evergreen Docs Planning Session 2009

5,584 views

Published on

Slides used in a 3-hour planning session for project-wide documentation coordination at Evergreen International Conference 2009.

Published in: Education, Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
5,584
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
19
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Evergreen Docs Planning Session 2009

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

×