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

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

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

6. We’re an open source STEREOTYPE!!!!

7. Current Formats: The 3 Ws
• Wiki — the Dokuwiki instance
• Word — word processing documents
• Whatever — PDF, text, random formats
for movies, audio, etc.

8. With every additional format,
another kitten dies.

9. And not the best
of first
impressions!

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

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

12. Resources and Opportunities
• Growing perception of need
• Critical mass
• Good communication tools
• Areas of in-house expertise
• Wide assistance/input from other
FOSS projects

13. The People…

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

15. The Plan…

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

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

18. The Pickaxe…

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

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

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

22. Significant OSS DocBook Implementations
• Linux
• Fedora
• PostgreSQL
• PHP
• TortoiseSVN
• Subversion
• FreeBSD
• Gnome

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

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

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. Essential DocBook Resources
• Web: Docbook.org
• Email list: Docbook-apps
• Book: Norman Walsh, DocBook: The Definitive Guide
• Book: Robert Stayton, DocBook XSL, 4th Edition

29. DIGGER Group Commitments
• Single-source documentation
• DocBook format
• Accept content “by any means necessary”

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

31. Think of the kittens.
Help the DIGGER Project!