OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[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!


| 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]