Open Stack

Steve, just saw this. What a great idea to get doc concerns into the blueprint, right up front with planning!

And Anne's listing looks right as well. ..sound of clapping..

cheers, Summer

-- 
Summer Long 
OpenStack Documentation Lead 
Engineering Content Services 

Red Hat Asia Pacific 
Brisbane, Australia 
slong at redhat.com | irc: slong 

----- Original Message -----
> From: "Steve Gordon" <sgordon at redhat.com>
> To: "OpenStack Development Mailing List (not for usage questions)" <openstack-dev at lists.openstack.org>
> Cc: "openstack-docs" <openstack-docs at lists.openstack.org>
> Sent: Saturday, March 22, 2014 9:40:48 AM
> Subject: Re: [Openstack-docs] [openstack-dev] [Nova] Updates to Juno	blueprint review process
> 
> ----- 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-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>