<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Sat, Aug 2, 2014 at 12:53 PM, Eoghan Glynn <span dir="ltr"><<a href="mailto:eglynn@redhat.com" target="_blank">eglynn@redhat.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><br>
Thanks for the quick response Anne, just some further discussion inline.<br>
<div class=""><br>
> > Digging through the git fossil-record in the openstack-manuals repo,<br>
> > I think I've found at least a partial answer to my question in the<br>
> > form of this commit:<br>
> ><br>
> > <a href="https://github.com/openstack/openstack-manuals/commit/cb407504" target="_blank">https://github.com/openstack/openstack-manuals/commit/cb407504</a><br>
> ><br>
> > This seems to be exactly what I was looking for: a lightweight model<br>
> > for contributions to documentation using a simple, widely-understood<br>
> > format (in this case, reStructuredText).<br>
> ><br>
><br>
> Yes we are experimenting with it for the Heat Orchestration (HOT)<br>
> Templates, a chapter to go into the End User Guide.<br>
<br>
</div>Cool.<br>
<br>
Is the other content in the end-user guide also going to start off<br>
as RST just like the HOT chapter, or will it be mixed source?<br>
(i.e. some RST, some native docbook)<br>
<div class=""><br>
> > My follow-on questions would be:<br>
> ><br>
> > * is this model only possible if the content is being targetted<br>
> > at a brand new guide, as opposed to a new chapter in an existing<br>
> > guide (such as the admin guide)?<br>
> ><br>
> ><br>
> Right, we didn't want to start up a whole new document, so we need a<br>
> chapter in an existing. Sorry you missed that conversation at the Summit.<br>
<br>
</div>Well, if by the summit conversation you mean this session:<br>
<br>
<a href="https://etherpad.openstack.org/p/beefing-up-user-and-operations-guides" target="_blank">https://etherpad.openstack.org/p/beefing-up-user-and-operations-guides</a><br>
<br>
I was there and recall the decision to put ceilometer into a new section<br>
of the existing guide.<br></blockquote><div><br></div><div>Ok, great. Sorry for not remembering. :)</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
My question was more along the lines of: *given* that we've decided<br>
to put the ceilometer content into a new chapter of an existing guide,<br>
would that decision make it impossible to use the new lightweight RST<br>
contribution model?<br>
<br></blockquote><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
(i.e. is that model only applicable to content going into new guides?)<br></blockquote><div><br></div><div>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. </div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div class=""><br>
> > * is the intent that the documentation team will take this RST<br>
> > content and translate it to docbook markup for PDF generation,<br>
> > or is it going to be used as-is in the documentation base?<br>
> ><br>
> ><br>
> It can go as-is if it's written well enough. We hope to automate, but these<br>
> are early steps.<br>
<br>
</div>Cool :)<br>
<div class=""><br>
> > * now that the ceilometer team has started down the road of making<br>
> > doc contributions in XML markup, would it makse sense to fully<br>
> > or partially switch to the lightweight RST approach at this stage?<br>
> ><br>
> ><br>
> Here's what I assert:<br>
> - Teams who tend to write in RST only tend to _not_ cover very complex<br>
> topic for operators. Keystone and federation and PKI comes to mind, as well<br>
> as Swift and storage policies. They write in RST, but not in a lot of depth<br>
> (more from the code perspective), so operators are hurting for good info<br>
> and best practices. I don't support an approach that continues this pain.<br>
<br>
</div>Sure, I *absolutely* want to ease this pain also.<br>
<br>
But TBH I didn't really see a strong connection between the format<br>
used to impart the information and the utility of that information to<br>
operators.<br>
<br>
(as long as the basic attributes are present in the format used, e.g.<br>
clarity, linkability, searchability, indexing etc.)<br></blockquote><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div class=""><br>
> I think pro writers use pro tools and have the ability to advocate for a<br>
> particular audience.<br>
<br>
</div>Absolutely agree in the case of professional writers. The time invested<br>
in getting these pro writers up to speed with the professional tooling is<br>
of course time spent, as it'll pay off again and again into the future.<br>
<br>
So no question from my side that the documentation team should continue<br>
to choose whatever tooling that works for them.<br>
<br>
My train of thought was simply that the RoI calculus for this ramp-up<br>
period is a bit different for non-professional writers, i.e. external<br>
project team members occasionally contributing content into the docs<br>
pipeline.<br>
<div class=""><br>
> - Standing up new guides again and again is not what we want, it won't<br>
> scale well and it's away from where I want us to go. I would like to get<br>
> away from such a book model but we'll need a new framework for that. I'm<br>
> working on web design prior to moving to a new framework. We will still<br>
> need books but we also need a page approach, and we're working on that in<br>
> stages. So for now we fit into titles we have rather than continuing to add<br>
> more book titles. We are adding References Guides that can be automated<br>
> when we can since they are less time-consuming.<br>
<br>
</div>Agreed that the proliferation of new guides is not the way to go.<br>
<div class=""><br>
> - Complex doc needs require complex doc tools. We don't have a translation<br>
> toolchain in place for RST/Sphinx. We don't have a way to cross-include<br>
> content across projects in a meaningful way. We can't make print-ready PDF<br>
> from RST/Sphinx that's as high quality as the set we sell on Lulu. I can't<br>
> quickly drop those requirements just to add easier authoring.<br>
> - We don't have to rely only on devs for good docs. If you're having a hard<br>
> time finding resources then we need to find a technical writing resource<br>
> for your team. Being at Redhat you should have Docbook experts available to<br>
> you -- let's figure out how to connect you to technical writing resources<br>
> so your developers don't struggle.<br>
<br>
</div>Well, given that time is short here, with juno-3 looming less<br>
than 5 weeks away, I wouldn't have huge confidence in locating<br>
Docbook-expert resources in Red Hat who are re-assignable and<br>
in a position to ramp up on ceilometer in time to make a difference<br>
to getting this effort over the line.<br>
<br>
So my instinct would be that we need to figure this out within<br>
the constraints of the existing resources.<br>
<br>
If I'm hearing you correctly, it seems that we should stick with<br>
the XML-markup for this effort, as reverting the RST would not be<br>
a practical proposition.<br>
<br>
In that case, I think we should try to streamline the process in<br>
other, more limited, ways.<br>
<br>
One thing that I think could be useful would be to have a<br>
well-defined agreed signal to indicate that the project-team<br>
author is satisfied with the initial rough content from a<br>
technical correctness and completeness PoV, and would like the<br>
documentation team to start with the revision/polish process on<br>
the content.<br>
<br>
Perhaps we could agree that the author removing their WIP -1<br>
on their patch(es) could act as that hand-over point?<br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
So as long as the WIP -1 is still in place, the project author is<br>
still iterating over the content for correctness & completeness.<br>
Once that flag is taken off, it's open season on getting the doc<br>
team's polish applied and the patch landed.<br>
<br>
Would that kind of approach make sense?<br></blockquote><div><br></div><div>Yep, this is how the review process works now. I apologize for violating it originally. </div><div>Anne </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Thanks,<br>
Eoghan<br>
</blockquote></div><br></div></div>