Open Stack

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.

Cheers,
Eoghan