Open Stack

----- Original Message -----
> From: "Steve Gordon" <sgordon at redhat.com>
> To: "openstack-docs" <openstack-docs at lists.openstack.org>
> Sent: Wednesday, November 20, 2013 10:28:24 AM
> Subject: [Openstack-docs] Fwd: [openstack-dev] [Nova] Blueprint review	process
> 
> 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)?

Anne reminded me on IRC that this is possibly something that would be addressed by the previously proposed "Project Docs Leads":

    https://wiki.openstack.org/wiki/Documentation/ProjectDocLeads

Maybe the solution to the issues I note above is to raise this again?

Thanks,

Steve