Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Evergreen Documentation Lightning Talk

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.)

  • Login to see the comments

Evergreen Documentation Lightning Talk

  1. 1. The Problem, Some People, A Plan, and a Pickaxe: A Report-Out from the May 20, 2009 Documentation Discussion Evergreen International Conference 2009 Karen G. Schneider, Equinox Software & Paul Weiss, Sage Library System
  2. 2. The Problem…
  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 ▫ Often duplicating/overlapping existing efforts and located here, there, everywhere
  4. 4. 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
  5. 5. We’re an open source STEREOTYPE!!!!
  6. 6. Current Formats: The 3 Ws • Wiki — the Dokuwiki instance • Word — word processing documents • Whatever — PDF, text, random formats for movies, audio, etc.
  7. 7. With every additional format, another kitten dies.
  8. 8. And not the best of first impressions!
  9. 9. 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
  10. 10. 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)
  11. 11. Resources and Opportunities • Growing perception of need • Critical mass • Good communication tools • Areas of in-house expertise • Wide assistance/input from other FOSS projects
  12. 12. The People…
  13. 13. 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
  14. 14. The Plan…
  15. 15. 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
  16. 16. 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
  17. 17. The Pickaxe…
  18. 18. 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
  19. 19. 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
  20. 20. 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
  21. 21. Significant OSS DocBook Implementations • Linux • Fedora • PostgreSQL • PHP • TortoiseSVN • Subversion • FreeBSD • Gnome
  22. 22. Getting to HTML Most writers will only see and work with these files. DocBook XML File* XSLT HTML Files Processor DocBook Stylesheet *May also include CSS and a Makefile
  23. 23. Common DocBook Toolset • DocBook-aware XML editors— XMLMind, Eclipse (free); oXygen, $ • XSL stylesheets (free, nice selection of default sheets on • 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
  24. 24. 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
  25. 25. Essential DocBook Resources • Web: • Email list: Docbook-apps • Book: Norman Walsh, DocBook: The Definitive Guide • Book: Robert Stayton, DocBook XSL, 4th Edition
  26. 26. DIGGER Group Commitments • Single-source documentation • DocBook format • Accept content “by any means necessary”
  27. 27. 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
  28. 28. Think of the kittens. Help the DIGGER Project!