----- 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
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
