[OPEN-ILS-DOCUMENTATION] Documentation Strategy Suggestion

[Karen Collier]

Fellow Documenters,

Admittedly, I have not been studying how other open source projects do documentation, but I do have some ideas on a workflow to improve the cohesiveness and organization of the documentation we produce.  They're based on what I've observed of the way code contributions are handled for Evergreen (the open source project I know best).

I think the documentation portion of the project could use people in roles analogous to the core contributors with commit privileges and someone in a role similar to the software release manager.

Those with documentation commit privileges take on the responsibility of proofreading documentation produced by others in the documentation team (or making sure someone has proofread it for grammar, style, etc.), converting it to DocBook format (if it's not already in that format), and committing it to the repository.

The person in the role of documentation release manager for a given release announces when there are release candidates of that upcoming software release available on the demo or dev server to use for testing and making screenshots, and calls for documentation volunteers to assume responsibility for updating or writing documentation for specific, manageable content areas.  Once a volunteer confirms completion of one small chunk they can volunteer for another if they want to.  Not to suggest people can't randomly submit patches to existing documentation as they stumble on problems, only to suggest that not be the primary way documentation is produced.

The goal of having a single person coordinating documentation work for a given release would be to channel volunteers so that everyone's checking a different piece of documentation to see if it is incomplete or requires updates to match the current release of the software, and making those changes.  And at the same time to make sure that (ideally and to the extent practical) every piece of existing documentation sees at least one critical pair of eyes (the person the release manager assigned to that portion) per release, rather than the current hit-or-miss approach.  The release manager could also collect people's suggestions on what documentation is missing and assign those areas to specific volunteers, again broken up into manageable chunks, for example "How to import records from a Marc file using Vandelay" rather than "Everything you ever wanted to know about using Vandelay."

In this sort of context, the learning curve that DocBook poses is completely irrelevant (assuming you have a large enough handful of core commiters who know DocBook), and the benefits come to the forefront.  You can include documentation on a given software release with that release, and it can be viewed, searched, and used in multiple formats (PDF, HTML, hard copy, etc) making it easy for the end user - ultimately our goal.

Thoughts?

Karen C

-- 
Karen Collier
Public Services Librarian
Kent County Public Library
408 High Street
Chestertown, MD 21620
410-778-3636