[OPEN-ILS-DOCUMENTATION] ***SPAM*** Re: For Discussion: DocBook Training

[Dan Scott]

On Thu, 2009-10-08 at 12:11 -0400, Karen Collier wrote:
> Hello again,
> 
> Remember I listed some proposed topics for the next meeting and said I'd open them up ahead of time for your consideration and early discussion?  Here's one.  But before you read on, don't forget to send in your preferences for the next meeting date and time.  http://www.doodle.com/9xi57vv8nddt85nn  We've had 7 people submit their preferences so far, but I know there are a lot more of you out there.  :)
> 
> Since we've decided XML based DocBook 5 is our format of choice for documentation, it makes sense for us to get as many people trained in producing and editing DocBook documentation as are willing to learn.  
> 
> As I understand it, Karen S and Shannon initially volunteered to participate in this training effort, though Karen S will no longer be able to.  So, I'm wondering who else feels they may be able and willing to participate in the DocBook training effort, whether in a Webinar training setting, by creating some annotated examples, by mentoring one or more individuals, or some other way I haven't thought of?  (please feel free to reply directly to the list, contact Shannon and me through docs at evergreen-ils.org, or feel free to speak up at the meeting)
> 
> Next, some questions for those who want to learn DocBook.  Which of the following would you personally find helpful?  (Again, reply to this email or write to open-ils-documentation at list.georgialibraries.org to contact the list, docs at evergreen-ils.org to contact Shannon and me, or speak up at the meeting.)
> 
> 1 - Training in Oxygen XML Editor (software available to nonprofits for $64/user, among other price options)
> 2 - Training in XMLMind (a WYSIWYG editor, free of charge)
> 3 - Training in another DocBook editor (Which do you have in mind?)
> 4 - Training in the tags and structure of docbook, independent of the specific tools
> 5 - Give me some examples of the basics with some explanation; I'll pick it up.
> 6 - Just point me to the information and I'll teach myself.
> 7 - I would appreciate being assigned a mentor who could help me figure this out.
> 8 - Other (What do you have in mind?)
> 
> Some questions for those not interested in learning DocBook.  Do you mind sharing why - too intimidating? no time? plan to be involved in testing or some other aspect that doesn't require it? some other reason?  Secondly, if not directly in DocBook what format(s) would you be willing to produce documentation in?
> 
> Any additional thoughts about DocBook training?

Hi Karen:

I've seen a variation on #5 work in some other projects (PHP & DB2).
These were projects where the contributions were being made by dozens of
different writers, but the goal was a single coherent set of
documentation that looks roughly like it was written with a single
voice. I think this maps pretty well to the DIG goals... Along with a
style guide and structure guide, you develop a few basic DocBook
template files and some corresponding samples of writing where those
templates have been fleshed out (following the style guide, etc). This
assumes that the form of documentation is topic-based, with one topic
per file, and that topics have standardized structures depending on
(say) whether they're a task topic, or a conceptual topic, or a
reference topic - big assumptions, I know.

For someone writing DocBook in a raw text editor, the templates guide
writers through the base set of DocBook tags that they need to worry
about when completing a given piece of documentation that conforms to
the project's structure for that kind of documentation, and the samples
let them do a quick lookup to see what they need to do to mark up
something a little out of the ordinary - like including a screenshot, or
linking to another section of documentation.

For someone writing DocBook in a more DocBook-aware editor, they should
be able to load the template and get rolling a bit faster, while still
being able to inspect the sample to get help in how the project does
something (rather than just the context-aware set of elements that are
legal at any given point in the document).

For someone just writing in a word processor who doesn't care about
DocBook, the transformed samples at least give them an idea of what to
aim for at a gross level (title, introduction, order of standard
subheadings, labels for diagrams or screenshots, etc) and that should
help the people converting that incoming contribution to DocBook make
the appropriate mapping, starting with cut and paste into sections and
then applying more refined markup thereafter.

For that matter, even the Linux Documentation Project offers templates
for their HOWTOs, although in that project the goal is consistency per
HOWTO rather than across the complete collection of HOWTOs.

So hopefully that's useful feedback. I can't commit to doing much in the
way of instruction or mentoring because I've got so much on my plate
already, but I want to say - thank you to all the DIGgers - you are an
inspiring example of how a team can come together to tackle a problem,
and I think you are showing us how the rest of the Evergreen community
needs to grow and evolve!