Open Stack

Steve, do you mean like a gap analysis between the projects and the
documentation? And share that with each project? And prompt them to provide
as much info as possible (with a tag for each undocumented item) as they
submit each doc bug. And link the docs bugs to this gap analysis to ensure
proper coverage? I'd be game for that :) Thank you for going deeper on
this. I hope everyone jumps in on this conversation. - Nermina


On Wed, Nov 20, 2013 at 10:28 AM, Steve Gordon <sgordon at redhat.com> wrote:

> Hi all,
>
> I've been musing for a while about the way we pick up changes that impact
> documentation, the timing of this is somewhat poor given our current bug
> backlog (as I suspect any improvement/solution would involve yet more work
> ;)) but thought I'd best open the discussion anyway to see what others
> thoughts are on this topic. Currently we get notification of a change that
> (potentially) impacts documentation when the change is merged and has the
> DocImpact flag set in the commit message.
>
> Reading over Russell's recent proposal on openstack-dev for improving the
> Nova blueprint process (forwarded in its entirety below) - an approach I'd
> love to see other PTLs adopt -  I noticed this statement in the context of
> what blueprint reviewers should be looking for before approving a blueprint:
>
> >  - includes information that describes the user impact (or lack of).
> >    Between the blueprint and text that comes with the DocImpact flag [3]
> >    in commits, the docs team should have *everything* they need to
> >    thoroughly document the feature.
>
> In isolation this is arguably "as it should be". What I think still makes
> me uneasy about the way we receive change notification in documentation is
> that:
>
> * Regardless of whether the above is achieved or not by the time we get
> notified the horse has bolted - the blueprint has been approved and the
> code has merged - so even if we *don't* in the end have enough information
> in the blueprint/commit there doesn't seem to be a feedback loop to the
> reviewers for next time. Instead we'd typically try and track down the
> author of the change directly and get the information from them, this works
> but adds an additional round of interactions and potential delays that
> could be avoided if we had better information up front.
>
> * While theoretically we should get a steady flow of inbound work over
> each code milestone there is (predictably) a big jump with the feature
> freeze and associated final milestone. I'm not sure there is any way to
> better prepare ourselves for this but I'm including this as a concern
> rather than something I have a solution for ;). In theory I think more
> concise blueprints and commit messages would at least help ensure that when
> this jump occurs the changes are more easily actionable for writers who
> aren't necessarily deeply aware of the ins and outs of every individual
> project.
>
> Personally I am going to attempt to pay closer attention to blueprints
> coming through and provide commentary (although it's already really too
> late for icehouse-1 - time flies when you are having fun!), but I was
> wondering if there is interest in being more proactive/organized approach
> to this from the wider documentation team (I'm thinking something like
> trying to have one person from docs review blueprints from each
> core/integrated project or something like that)?
>
> Thanks,
>
> Steve, your friendly rambling lunatic ;).
>
> ----- Forwarded Message -----
> > From: "Russell Bryant" <rbryant at redhat.com>
> > To: "OpenStack Development Mailing List" <
> openstack-dev at lists.openstack.org>
> > Sent: Wednesday, October 23, 2013 11:33:14 AM
> > Subject: [openstack-dev] [Nova] Blueprint review process
> >
> > Greetings,
> >
> > At the last Nova meeting we started talking about some updates to the
> > Nova blueprint process for the Icehouse cycle.  I had hoped we could
> > talk about and finalize this in a Nova design summit session on "Nova
> > Project Structure and Process" [1], but I think we need to push forward
> > on finalizing this as soon as possible so that it doesn't block current
> > work being done.
> >
> > Here is a first cut at the process.  Let me know what you think is
> > missing or should change.  I'll get the result of this thread posted on
> > the wiki.
> >
> > 1) Proposing a Blueprint
> >
> > Proposing a blueprint for Nova is not much different than other
> > projects.  You should follow the instructions here:
> >
> >     https://wiki.openstack.org/wiki/Blueprints
> >
> > The particular important step that seems to be missed by most is:
> >
> > "Once it is ready for PTL review, you should set:
> >
> > Milestone: Which part of the release cycle you think your work will be
> > proposed for merging."
> >
> > That is really important.  Due to the volume of Nova blueprints, it
> > probably will not be seen until you do this.
> >
> > 2) Blueprint Review Team
> >
> > Ensuring blueprints get reviewed is one of the responsibilities of the
> > PTL.  However, due to the volume of Nova blueprints, it's not practical
> > for me to do it alone.  A team of people (nova-drivers) [2], a subset of
> > nova-core, will be doing blueprint reviews.
> >
> > By having more people reviewing blueprints, we can do a more thorough
> > job and have a higher quality result.
> >
> > Note that even though there is a nova-drivers team, *everyone* is
> > encouraged to participate in the review process by providing feedback on
> > the mailing list.
> >
> > 3) Blueprint Review Criteria
> >
> > Here are some things that the team reviewing blueprints should look for:
> >
> > The blueprint ...
> >
> >  - is assigned to the person signing up to do the work
> >
> >  - has been targeted to the milestone when the code is
> >    planned to be completed
> >
> >  - is an appropriate feature for Nova.  This means it fits with the
> >    vision for Nova and OpenStack overall.  This is obviously very
> >    subjective, but the result should represent consensus.
> >
> >  - includes enough detail to be able to complete an initial design
> >    review before approving the blueprint. In many cases, the design
> >    review may result in a discussion on the mailing list to work
> >    through details. A link to this discussion should be left in the
> >    whiteboard of the blueprint for reference.  This initial design
> >    review should be completed before the blueprint is approved.
> >
> >  - includes information that describes the user impact (or lack of).
> >    Between the blueprint and text that comes with the DocImpact flag [3]
> >    in commits, the docs team should have *everything* they need to
> >    thoroughly document the feature.
> >
> > Once the review has been complete, the blueprint should be marked as
> > approved and the priority should be set.  A set priority is how we know
> > from the blueprint list which ones have already been reviewed.
> >
> > 4) Blueprint Prioritization
> >
> > I would like to do a better job of using priorities in Icehouse.  The
> > priority field services a couple of purposes:
> >
> >   - helps reviewers prioritize their time
> >
> >   - helps set expectations for the submitter for how reviewing this
> >     work stacks up against other things
> >
> > In the last meeting we discussed an idea that I think is worth trying at
> > least for icehouse-1 to see if we like it or not.  The idea is that
> > *every* blueprint starts out at a Low priority, which means "best
> > effort, but no promises".  For a blueprint to get prioritized higher, it
> > should have 2 nova-core members signed up to review the resulting code.
> >
> > If we do this, I suspect we may end up with more blueprints at Low, but
> > I also think we'll end up with a more realistic list of blueprints.  The
> > reality is if a feature doesn't have reviewers agreeing to do the
> > review, it really is in a "best effort, but no promises" situation.
> >
> > 5) Blueprint Fall Cleaning
> >
> > Finally, it's about time we do some cleaning of the blueprint backlog.
> > There are a bunch not currently being worked on.  I propose that we
> > close out all blueprints not targeted at a release milestone by November
> > 22 (2 weeks after the end of the design summit), with the exception of
> > anything just recently filed and still being drafted.
> >
> >
> > [1] http://summit.openstack.org/cfp/details/341
> > [2] https://launchpad.net/~nova-drivers/+members#active
> > [3]
> >
> http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/
> >
> > --
> > Russell Bryant
> >
> > _______________________________________________
> > OpenStack-dev mailing list
> > OpenStack-dev at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
>
> --
> Steve Gordon, RHCE
> Product Manager, Red Hat OpenStack
> Red Hat Canada (Toronto, Ontario)
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Thank you!

Nermina Miller
Tech Writer and Editor
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131120/7ebc4dfc/attachment-0001.html>