Open Stack

----- Original Message -----
> We recently discussed the idea of using gerrit to review blueprint
> specifications [1].  There was a lot of support for the idea so we have
> proceeded with putting this together before the start of the Juno
> development cycle.
> 
> We now have a new project set up, openstack/nova-specs.  You submit
> changes to it just like any other project in gerrit.  Find the README
> and a template for specifications here:
> 
>   http://git.openstack.org/cgit/openstack/nova-specs/tree/README.rst
> 
>   http://git.openstack.org/cgit/openstack/nova-specs/tree/template.rst

Adding the documentation team - the above is the template for nova blueprints under the new process, at the time of writing the documentation impact section reads:

"""
Documentation Impact
====================

What is the impact on the docs team of this change? Some changes might require
donating resources to the docs team to have the documentation updated. Don't
repeat details discussed above, but please reference them here.
"""

Under the current procedure documentation impact is only really directly addressed when the code itself is committed, with the DocImpact tag in the commit message, and a documentation bug is raised via automation. The above addition to the blueprint template offers a good opportunity to start thinking about the documentation impact, and articulating it much earlier in the process*.

I'm wondering if we shouldn't provide some more guidance on what a good documentation impact assessment would like though, I know Anne previously articulated some thoughts on this here:

    http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/

TL;DR:

* Who would use the feature?
* Why use the feature?
* What is the exact usage for the feature?
* Does the feature also have permissions/policies attached? 
* If it is a configuration option, which flag grouping should it go into? 

Do these questions or some approximation of them belong in the template? Or can we do better? Interested in your thoughts :). On a separate note a specific type of documentation I have often bemoaned not having a field in launchpad for is a release note. Is this something separate or does it belong in documentation impact? A good release note answers most if not all of the above questions but is also short and concise.

Thanks,

Steve