[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [docbook-apps] Proposing a DocBooks workflow for an open source community
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]