Your SlideShare is downloading. ×
Evergreen Documentation Lightning Talk
Upcoming SlideShare
Loading in...5

Thanks for flagging this SlideShare!

Oops! An error has occurred.


Saving this for later?

Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime - even offline.

Text the download link to your phone

Standard text messaging rates apply

Evergreen Documentation Lightning Talk


Published on

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

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

Published in: Technology

1 Comment
  • Be the first to like this

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

No notes for slide


  • 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. The Problem…
  • 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. 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. We’re an open source STEREOTYPE!!!!
  • 6. Current Formats: The 3 Ws • Wiki — the Dokuwiki instance • Word — word processing documents • Whatever — PDF, text, random formats for movies, audio, etc.
  • 7. With every additional format, another kitten dies.
  • 8. And not the best of first impressions!
  • 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. 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. 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. The People…
  • 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. The Plan…
  • 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. 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. The Pickaxe…
  • 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. 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. 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. Significant OSS DocBook Implementations • Linux • Fedora • PostgreSQL • PHP • TortoiseSVN • Subversion • FreeBSD • Gnome
  • 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. 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. 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. Essential DocBook Resources • Web: • Email list: Docbook-apps • Book: Norman Walsh, DocBook: The Definitive Guide • Book: Robert Stayton, DocBook XSL, 4th Edition
  • 26. DIGGER Group Commitments • Single-source documentation • DocBook format • Accept content “by any means necessary”
  • 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. Think of the kittens. Help the DIGGER Project!