<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Mar 21, 2014 at 4:40 PM, Steve Gordon <span dir="ltr"><<a href="mailto:sgordon@redhat.com" target="_blank">sgordon@redhat.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class="">----- Original Message -----<br>
> We recently discussed the idea of using gerrit to review blueprint<br>
> specifications [1].  There was a lot of support for the idea so we have<br>
> proceeded with putting this together before the start of the Juno<br>
> development cycle.<br>
><br>
> We now have a new project set up, openstack/nova-specs.  You submit<br>
> changes to it just like any other project in gerrit.  Find the README<br>
> and a template for specifications here:<br>
><br>
>   <a href="http://git.openstack.org/cgit/openstack/nova-specs/tree/README.rst" target="_blank">http://git.openstack.org/cgit/openstack/nova-specs/tree/README.rst</a><br>
><br>
>   <a href="http://git.openstack.org/cgit/openstack/nova-specs/tree/template.rst" target="_blank">http://git.openstack.org/cgit/openstack/nova-specs/tree/template.rst</a><br>
<br>
</div>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:<br>
<br>
"""<br>
Documentation Impact<br>
====================<br>
<br>
What is the impact on the docs team of this change? Some changes might require<br>
donating resources to the docs team to have the documentation updated. Don't<br>
repeat details discussed above, but please reference them here.<br>
"""<br>
<br>
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*.<br>


<br>
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:<br>
<br>
    <a href="http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/" target="_blank">http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/</a><br>
<br>
TL;DR:<br>
<br>
* Who would use the feature?<br>
* Why use the feature?<br>
* What is the exact usage for the feature?<br>
* Does the feature also have permissions/policies attached?<br>
* If it is a configuration option, which flag grouping should it go into?<br>
<br>
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.<br>

</blockquote><div><br></div><div>The template should answer all the questions highlighted on <a href="http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/" target="_blank">http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/</a> as we need the same information to review the blueprint itself. If not its a bug.</div>

<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Thanks,<br>
<br>
Steve<br>
<div class=""><div class="h5"><br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br></div></div>