Open Stack

On Sat, Aug 2, 2014 at 12:53 PM, Eoghan Glynn <eglynn at redhat.com> wrote:

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

Ok, great. Sorry for not remembering. :)


>
> 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 think so at this point... I don't think we have the lightweight
completely solved and there's still the problem of a sense of abandonment
in RST docs. Plus the patch is nearly done, and the reviews are working as
expected.


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

Not necessarily, I'd certainly consider adding a new reference guide, but
don't have a resource identified to do the work. Plus it doesn't alleviate
your original difficulty.


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

Sure. I agree, and that's why I want to move towards a new page-based
framework, but we're not there yet. Nor will we be soon.


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

Yep, this is how the review process works now. I apologize for violating it
originally.
Anne


>
> Thanks,
> Eoghan
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140803/51a97f00/attachment-0001.html>