Open Stack

On Thu, Feb 26, 2015 at 1:45 PM, Stefano Maffulli <stefano at openstack.org>
wrote:

> On Wed, 2015-02-25 at 21:15 +0000, Ian Cordasco wrote:
> > I read it the same was as Doug. I don’t think Jeremy was trying to
> > imply your reviews would move through more quickly if you reviewed
> > other people’s work. Just that, as with most open source projects,
> > there’s always at least 2 distinct groups: people who push code more
> > often and people who review code more often.
>
> this conversation reminded me that the median time to merge new code has
> been increasing every quarter in the past year, but dropped for the
> first time during last quarter (table and chart on page 23 of Q4
> quarterly report [1]). The mean number of iterations (patchsets) per
> proposed change has also decreased for the first time in Q4 2014.
>
> The interesting bit of those charts is that overall for OpenStack
> projects, it seems that the reviews (comments to patchsets) are arriving
> quite quickly but the new patchsets take a lot more to be submitted.
>
> Too much debating and commenting over each patch? Or are the
> authors/owners of the changeset slow to respond with new patches? I
> don't have an answer. I'd be happy to look at the data with other
> people.
>
> I think more analysis is needed before we can identify and remove the
> problem.
>
> /Stef
>
>  [1]
>
> http://git.openstack.org/cgit/openstack-infra/activity-board/plain/reports/2014-q4/pdf/2014-q4_OpenStack_report.pdf
> The analysis doesn't count the *-specs repositories, only code and docs.
>
>
Thanks for the analysis Stef. One additional analysis I would like to see
is this:

Do the features listed in the Release Notes each have appropriate
documentation? So far we just link to the specifications for nova, for
example. [1] So to me, it could be a focus on the specification acceptance
means less time/energy for the actual user-facing docs.

What could I do to analyze and correlate the feature completeness to doc
completeness? A desire to release docs with code is great but we don't seem
to be doing so in the way that I define docs being done.

I've worked with Agile teams in the past, and you have to put your
definition of done for docs in with the code. Often times, it's "release
notes only" in the definition of done. So I think we're working at that
level of "done" for docs, instead of "end user docs complete" or "API docs
complete" or "config docs complete" or "administration documented" as the
marker of complete for release.

We've seen with the python-<project>clients that the docs are very much
complained about. The release cadence doesn't really give docs a chance to
do anything but scrape the help text to automate a collection of
information about each command in the CLI Reference. [2] That's one
solution but one that serves speed rather than quality. Users tell me
they'd prefer to have commands for use cases and scenarios in the docs,
which is closer to our End User Guide. [3] But even the End User Guide
could be improved by showing examples of what's returned for each command.
We've only got about 10% coverage there.

We're doing everything we can to make it easier to contribute to docs by
migrating to RST,[4] so let's please consider an energy transfer from specs
acceptance to end-user docs, especially during feature freeze time.

Kept meaning to note the difficulties for docs on the other thread, but
Stef's email reminds me we need more analysis as well.
Thanks,
Anne

1.
https://wiki.openstack.org/wiki/ReleaseNotes/Juno#OpenStack_Compute_.28Nova.29
2. http://docs.openstack.org/cli-reference/content/
3. http://docs.openstack.org/user-guide/content/
4. http://justwriteclick.com/2015/02/23/state-of-the-migration-to-sphinxrst/


> PS The analysis of the individual projects are in their own pdf
>
> http://git.openstack.org/cgit/openstack-infra/activity-board/tree/reports/2014-q4/pdf/projects
>
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150226/d9bcf14d/attachment.html>