Open Stack

Hi Eoghan, thanks for bringing this to the mailing list.


On Wed, Jul 30, 2014 at 10:08 AM, Eoghan Glynn <eglynn at redhat.com> wrote:

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

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?

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.

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.


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


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

Anne


> 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
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140731/58201c8f/attachment.html>