Open Stack

> > Eoghan, I just can't let this go without saying something. The TC doesn't
> > put these requirements in place as once-off tasks. We put them in place so
> > that you can support the people who need to keep ceilometer running every
> > day. Not as a barrier to entry, but to ensure OpenStack means that you can
> > get consistent docs to help you run OpenStack.
> 
> Sure, I *absolutely* understand the need for quality docs,
> having been in an ops environment in a past life :)
> 
> I didn't mean that the production of documentation, in general,
> is a once-off task, nor that any of the other TC-mandated
> requirements are once-off tasks.
> 
> Rather that the involvement of individual ceilometer project
> contributors in getting tooled up to contribute directly to
> documentation as part of a full-court-press to get the project
> docco up to standard is from their *individual* PoV unlikely to
> be an oft-repeated task.
> 
> Instead they will likely spend the majority of their contribution
> time working on the python codebase as opposed to documentation.
> 
> Apologies if I'm way off-base here in my attempts to simplify the
> learning-curve for contributors to the documentation-base.
> 
> But I would really appreciate it if we could round out this
> thread with an answer to the question I've raised:
> 
>  is it possible for the documentation contribution workflow to be
>  streamlined so that it isn't necessary for project contributors
>  to learn the XML-markup and PDF-generation toolchain?

Digging through the git fossil-record in the openstack-manuals repo,
I think I've found at least a partial answer to my question in the
form of this commit:

  https://github.com/openstack/openstack-manuals/commit/cb407504

This seems to be exactly what I was looking for: a lightweight model
for contributions to documentation using a simple, widely-understood
format (in this case, reStructuredText).

My follow-on questions would be:

 * is this model only possible if the content is being targetted
   at a brand new guide, as opposed to a new chapter in an existing
   guide (such as the admin guide)?

 * is the intent that the documentation team will take this RST
   content and translate it to docbook markup for PDF generation,
   or is it going to be used as-is in the documentation base?

 * now that the ceilometer team has started down the road of making
   doc contributions in XML markup, would it makse sense to fully
   or partially switch to the lightweight RST approach at this stage?

Any further clarity on those points would be much appreciated! :)

Thanks,
Eoghan