Open Stack

On Thu, Jul 31, 2014 at 3:09 PM, Eoghan Glynn <eglynn at redhat.com> wrote:

>
> Thanks for the response Anne,
>
> > > Which is fine, I just need to level-set the expectations here,
> > > since the ceilometer team is on the hook for a TC-mandated gap
> > > coverage task[2] and also has a bunch of other stuff on its
> > > plate.
> > >
> >
> > I'd like to continue to enable the docs team to provide the additional
> > polish and editing. Is your concern the timeline? Or that the team's
> > efforts appears to be less than desired?
>
> Actually it was more confusion on my part, due to the comments dating
> from yesterday on:
>
>
> https://review.openstack.org/#/c/108741/7/doc/admin-guide-cloud/ch_telemetry.xml
>
> which referred to revisions, which I then assumed meant a *separate*
> patch, as the revised patchset wasn't pushed until today (I see now
> from the comments trail in gerrit that this was just a simple oversight).
>
> > If your concern is the timeline, we can certainly push through what is
> > considered "good enough" by the project team. However we merged 20
> patches
> > yesterday so I don't think that's what you're talking about.
>
> I'm somewhat concerned with timelines, since we're on the hook to get
> this done by juno-3 (plus a lot of other things).
>
> However I'm mostly concerned with just clarifying and streamlining
> the workflow, so that as to minimize the friction involved in
> getting this over the line.
>
> Potential points of friction include:
>
>  * our lack of clarity of the contribution model preferred by the
>    documentation team
>
>  * our unfamiliarity with the documentation tool-chain
>
> > If your concern is that the writing is being rejected somewhat, let's
> talk
> > some more about that. For the most part the core-docs team have a really
> > good sense of the voice and style we aim to achieve.
>
> Well, I'm perfectly happy for the "house style" to be applied,
> so no problem with that step in the workflow, now I understand it
> involves polishing the original patch and re-submitting that as
> opposed to a fresh proposal.
>
> In fact the other approach of content being re-proposed as fresh
> patches could alternatively work well ... but my point was simply
> that if extensive rewrites are applied as a matter of course then
> there doesn't seem to a pressing need for the content submitted by
> the project team to be *already* in the unfamiliar XML mark-up.
>
> > > If the workflow is based on rough content being provided by the
> > > project team, which is then polished up by the docco team, then I
> > > think we really need to streamline this process to avoid burning
> > > time unnecessarily getting to grips with the XML-based markup and
> > > maven-based build system.
> > >
> > > For example, would it make more sense for the raw content to be
> > > submitted initially in a simple lightweight form, such as free-
> > > form text or .rst or wiki markup?
> > >
> >
> > Really, what you describe is happening already. The lightweight docs
> tools
> > remain in the <project> repos. The heavyweight docs tools are the ones
> that
> > are integrated across projects. This separation is by design with the
> > following benefits in mind:
> > - docs team knows cross-project consistency
> > - translations are enabled for these deliverables
> > - docs team manages scope and priority for cross-project docs
> > - docs team understands operators, administrators, users deliverables
>
> OK, but in this case the project team has strayed into the domain
> of the "heavyweight docs tools" - should we have stayed out of that
> domain and instead crafted the content in the first instance back in
> the project repo and have it fed into docs from there?
>
> > > That would allow the domain expertise of the project team to be
> > > leveraged, without imposing an unnecessary burden, while at the
> > > same time getting the most RoI for the time spent by the docco
> > > team revising the formatting according to their own particular
> > > domain expertise.
> > >
> > >
> > Believe me, I'm working on getting the ROI calculation reversed a bit by
> > introducing new tools, but for now the system is working as designed. I'd
> > be happy to hear more tweaks.
>
> Understood! :)
>
> I'm sure the RoI from this tooling is already strong on the docs
> team, I'm more questioning the return from the learning curve of
> the project-team to use this mark-up and toolchain for essentially
> a once-off task.
>

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.

We are working on ways to enable more simple markup in our toolchain. The
most recent is the Heat Orchestration Template (HOT) Guide. Stay tuned for
more as we keep onboarding more integrated projects.
Thanks,
Anne


>
> Cheers,
> Eoghan
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140801/e4b90821/attachment.html>