Open Stack

On Sat, Aug 2, 2014 at 11:25 AM, Eoghan Glynn <eglynn at redhat.com> wrote:

>
>
> > > 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).
>

Yes we are experimenting with it for the Heat Orchestration (HOT)
Templates, a chapter to go into the End User Guide.


>
> 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)?
>
>
Right, we didn't want to start up a whole new document, so we need a
chapter in an existing. Sorry you missed that conversation at the Summit.


>  * 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?
>
>
It can go as-is if it's written well enough. We hope to automate, but these
are early steps.


>  * 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?
>
>
Here's what I assert:
- Teams who tend to write in RST only tend to _not_ cover very complex
topic for operators. Keystone and federation and PKI comes to mind, as well
as Swift and storage policies. They write in RST, but not in a lot of depth
(more from the code perspective), so operators are hurting for good info
and best practices. I don't support an approach that continues this pain. I
think pro writers use pro tools and have the ability to advocate for a
particular audience.
- Standing up new guides again and again is not what we want, it won't
scale well and it's away from where I want us to go. I would like to get
away from such a book model but we'll need a new framework for that. I'm
working on web design prior to moving to a new framework. We will still
need books but we also need a page approach, and we're working on that in
stages. So for now we fit into titles we have rather than continuing to add
more book titles. We are adding References Guides that can be automated
when we can since they are less time-consuming.
- Complex doc needs require complex doc tools. We don't have a translation
toolchain in place for RST/Sphinx. We don't have a way to cross-include
content across projects in a meaningful way. We can't make print-ready PDF
from RST/Sphinx that's as high quality as the set we sell on Lulu. I can't
quickly drop those requirements just to add easier authoring.
- We don't have to rely only on devs for good docs. If you're having a hard
time finding resources then we need to find a technical writing resource
for your team. Being at Redhat you should have Docbook experts available to
you -- let's figure out how to connect you to technical writing resources
so your developers don't struggle.


> Any further clarity on those points would be much appreciated! :)
>
>
Hope this explanation helps, thanks for asking! We're iterating on these
ideas based on all the good input we get. :)

Anne


> Thanks,
> Eoghan
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140802/81bd3c3a/attachment.html>