Open Stack

Folks,

I raised this question earlier on #os-doc IRC, but I suspect that
I might get more clarity by bringing it to the ML instead.

So basically I'd like to just clarify the workflow envisaged by
the "I revised this in a subsequent patch ..." comments on [1].

My initial assumption about the workflow was:

  1. ceilometer team proposes docco patches to gerrit
  2. documentation team comments on gerrit and suggests changes
  3. ceilometer team's patches eventually land in the
     openstack-manuals git repo

But in the light of those comments on gerrit, it seems more like:

  1. ceilometer team proposes docco patches to gerrit
  2. documentation team rewrites those patches to their liking
     and then re-proposes fresh patches
  3. documentation team's version of the patches land in the
     openstack-manuals git repo

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.

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?

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.

Cheers,
Eoghan

[1] https://review.openstack.org/#/c/108741/7/doc/admin-guide-cloud/ch_telemetry.xml
[2] https://wiki.openstack.org/wiki/Governance/TechnicalCommittee/Ceilometer_Gap_Coverage#Concern_.232:_lack_of_user-_and_operator-oriented_documentation