Open Stack

On 21/11/13 12:36, Steve Gordon wrote:
> ----- Original Message -----
>> From: "Tom Fifield" <tom at openstack.org>
>> To: openstack-docs at lists.openstack.org
>> Sent: Wednesday, November 20, 2013 8:23:19 PM
>> Subject: Re: [Openstack-docs] Fwd: [openstack-dev] [Nova] Blueprint review process
>>
>> On 21/11/13 02:28, Steve Gordon 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 ;).
>>
>> Just data points:
>>
>> * We used to have DocImpact bug creation / email on first patchset
>> submission - even while WIP or Draft.
>> * We changed this to only create bugs after patches were merged
>> * This was because,
>> 1) The emails were more or less useless
>> 2) There was requirement for constant followup on reviews with lodged
>> bugs to check the status, which ended up not getting done regularly
>> anyway (I just waited for weeks and did a bunch once I knew the
>> likelihood of them being merged was high) because it was simply too much
>> work for one person doing it in their spare time
>
> I'm not really suggesting we go back to trying to run ahead and guess what will land - as I said above I'm not sure there is a better way to deal with the natural flow of changes over the duration of the cycle. Rather I'm suggesting that more thorough blueprints would potentially lead to it being more easy for someone to "pick up" the documentation bug coming out the other end once a change lands.
>
> Of course stating that is the easy part, working out how to actually enable that - with already scarce resources from our side - is the complicated part.
>
> Thanks,
>
> Steve

No argument from me there :)

One of my TODO list checks for release time is to read all the 
blueprints, I think they are a good starting point. There's also been a 
nice push from the dev community to make the descriptions (normally in 
linked wiki pages) better, which supports this.


Regards,


Tom