Open Stack

On Fri, Mar 21, 2014 at 4:40 PM, Steve Gordon <sgordon at redhat.com> wrote:

> ----- 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.
>

The template should answer all the questions highlighted on
http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/ as
we need the same information to review the blueprint itself. If not its a
bug.


>
> Thanks,
>
> Steve
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140324/3d3f3869/attachment.html>