Open Stack

Thanks for the quick response Anne, just some further discussion inline.

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

Cool.

Is the other content in the end-user guide also going to start off
as RST just like the HOT chapter, or will it be mixed source?
(i.e. some RST, some native docbook)

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

Well, if by the summit conversation you mean this session:

  https://etherpad.openstack.org/p/beefing-up-user-and-operations-guides

I was there and recall the decision to put ceilometer into a new section
of the existing guide.

My question was more along the lines of: *given* that we've decided
to put the ceilometer content into a new chapter of an existing guide,
would that decision make it impossible to use the new lightweight RST
contribution model?

(i.e. is that model only applicable to content going into new guides?)

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

Cool :)

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

Sure, I *absolutely* want to ease this pain also.

But TBH I didn't really see a strong connection between the format
used to impart the information and the utility of that information to
operators.

(as long as the basic attributes are present in the format used, e.g.
clarity, linkability, searchability, indexing etc.)

> I think pro writers use pro tools and have the ability to advocate for a
> particular audience.

Absolutely agree in the case of professional writers. The time invested
in getting these pro writers up to speed with the professional tooling is
of course time spent, as it'll pay off again and again into the future.

So no question from my side that the documentation team should continue
to choose whatever tooling that works for them.

My train of thought was simply that the RoI calculus for this ramp-up
period is a bit different for non-professional writers, i.e. external
project team members occasionally contributing content into the docs
pipeline.

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

Agreed that the proliferation of new guides is not the way to go.

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

Well, given that time is short here, with juno-3 looming less
than 5 weeks away, I wouldn't have huge confidence in locating
Docbook-expert resources in Red Hat who are re-assignable and
in a position to ramp up on ceilometer in time to make a difference
to getting this effort over the line.

So my instinct would be that we need to figure this out within
the constraints of the existing resources.

If I'm hearing you correctly, it seems that we should stick with
the XML-markup for this effort, as reverting the RST would not be
a practical proposition.

In that case, I think we should try to streamline the process in
other, more limited, ways.

One thing that I think could be useful would be to have a
well-defined agreed signal to indicate that the project-team
author is satisfied with the initial rough content from a
technical correctness and completeness PoV, and would like the
documentation team to start with the revision/polish process on
the content.

Perhaps we could agree that the author removing their WIP -1
on their patch(es) could act as that hand-over point?

So as long as the WIP -1 is still in place, the project author is
still iterating over the content for correctness & completeness.
Once that flag is taken off, it's open season on getting the doc
team's polish applied and the patch landed.

Would that kind of approach make sense?

Thanks,
Eoghan