Evergreen Documentation Lightning Talk

5,484 views

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

Published in: Technology
1 Comment
1 Like
Statistics
Notes
No Downloads
Views
Total views
5,484
On SlideShare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
7
Comments
1
Likes
1
Embeds 0
No embeds

No notes for slide

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 docbook.org) • 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: Docbook.org • 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!

×