Open Stack

The PDL can also identify new project contributors 'interns' that want to help and learn, and assign project doc bugs to cut their teeth on. Pipelining new project reviewers that just happen to think docs are important. 

~sean

> On Nov 20, 2013, at 8:02, "Steve Gordon" <sgordon at redhat.com> wrote:
> 
> ----- 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
> 
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs