[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]