RE: [docbook-apps] Proposing a DocBooks workflow for an open source community

["Eric Johnson" <EMJOHNSO@progress.com>]

Karen,
I work on a team that writes documentation for a commercial distribution
of open source projects using DocBook.

We've broken the tasks into 3 basic roles:
* Writing
* Templating
* Production

Currently writers do the writing. One person is assigned responsibility
for a release and handles the production for that release. We have an
automated build system that is driven by a TeamCity server, but some
team members are loathe to use it for some reason. Templating is handled
by a dedicated resource - they also do a bit of writing.

To ensure that all of the mark-up is consistent, we provide a mark-up
guide that outlines how we use the DocBook mark-up. There is a "mark-up
cop" that occasionally patrols the source making sure the writers are
using things correctly. Mostly this person touches up the mark-up and
gently reminds the offender to stick to the prescribed path.

For revision control we use SVN. It is easy to use and pretty robust. We
use SVN's external mechanism pretty extensively for common content
sharing. I've also heard the git is gaining some traction. We follow
pretty standard revision control procedures. Trunk is for the latest and
greatest. Releases are done from tags.

Our tool set is built using Ant, the DocBook XSLT, Saxon, and a
customization layer. It is fully cross-platform and easily automated.
Two goals of our tool set was to make it easy to incorporate updates to
the DocBook XSLT and to make it easy to toss over the wall to the open
source projects. We looked into using Maven, but didn't feel that any of
the plug-ins really worked the way we wanted. Ant also had the advantage
of letting us pick our own file structures.

Each contributor is responsible for maintaining relationships with both
our internal development team and the external communities working on
the open source project we distribute. There is one person whose role is
to coordinate requirements, planning, and releases with the internal
product teams.

Our basic level of modularity is a section. We use the generic section
element instead of the sectn elements to make the modules more flexible.
For our team this made the most sense. Anything bigger felt like too
much, but any thing smaller seemed too granular.

We are doing a decent amount of cross book sharing and it works pretty
well so far. We also have single sourced legal and copyright text that
is shared by all of our books. 

One member of our team is working on a tool for sharing content between
the DocBook source the confluence wikis used by the open source
communities. When he has it working, I believe the plan is to make it
available as an open source project.

Cheers,
Eric

-----Original Message-----
From: Karen Schneider [mailto:kgschneider@gmail.com] 
Sent: Wednesday, April 22, 2009 3:56 PM
To: docbook-apps
Subject: [docbook-apps] Proposing a DocBooks workflow for an open source
community

Hi folks, this is another high-level post--revisiting discussions from
a while back. Thanks for all the great responses to the workshop (I
still owe a couple people responses, but it's a nutty week).

I work for a support company associated with an open source project. I
have been looking at documentation workflows for similar companies and
projects. There are many ways to do this right, and everyone's
situation is different. But in general, it seems as if these might be
some suggested practices:

* Identify the varied tasks that need to be done, from writing to
DocBook production (e.g. the Linux project seems to be trying to do
this:
http://wiki.tldp.org/Task_list?action=show&redirect=Rewriting+Manifesto/
GettingInvolved
; Drupal also seems to do this as well: http://drupal.org/node/23743 )
* Develop a manual (e.g. see MySQL
http://dev.mysql.com/doc/mysqldoc-guide/en/fg.html )
* Focus on modular XML so the documentation can be thin-sliced as much
as possible (e.g. php.net does this)
* Implement tools/production methods that facilitate Docbook
generation -- e.g. php.net's own tool collection (very specific to
them, but an interesting model)
* Develop templates and style guidelines that maximize standardized,
streamlined input
* Use revision control and a central repository
* Establish a/several wrangler position(s) where at least one person,
somewhere, is where the buck stops for quality control, content
creation, CSS styling, interacting with the community, etc.
* Given limited resources, have flexibility in documentation
production -- e.g. the gold standard for format can be DocBook, but
don't turn down (or TAKE down) good documentation because it's
produced in something else!

Thoughts?

-- 
-- 
| Karen G. Schneider
| Community Librarian
| Equinox Software Inc. "The Evergreen Experts"
| Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
| kgs@esilibrary.com
| Web: http://www.esilibrary.com
| Be a part of the Evergreen International Conference, May 20-22, 2009!
| http://www.lyrasis.org/evergreen

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org