<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On 4 December 2015 at 11:22, Henry Gessau <span dir="ltr"><<a href="mailto:gessau@gmail.com" target="_blank">gessau@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">Sean M. Collins <<a href="mailto:sean@coreitpro.com">sean@coreitpro.com</a>> wrote:<br>
> I've noticed that a lot of features are now being documented as RSTs<br>
> inside of devref. Like the following:<br>
><br>
> <a href="https://review.openstack.org/#/c/251859/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/251859/</a><br>
><br>
> But there are lots already present. Can someone point out to me what the<br>
> criteria is for these documents? I am a little confused about the<br>
> relationship between neutron-specs, RFE bugs, and some features being<br>
> documented in devref. Especially when a review includes the actual code,<br>
> then a new RST file in devref - wasn't that what specs were for?<br>
<br>
</span>Here is how I would like to see things ending up:<br>
<br>
1. RFE: "I want X"<br>
2. Spec: "I plan to implement X like this"<br>
3. devref: "How X is implemented and how to extend it"<br>
4. OS docs: "API and guide for using X"<br>
<br>
Once X is implemented I don't want to have to go to 1 or 2 to find information<br>
on it. The devref may have a lot of content from the spec, but the spec is not<br>
maintained and the implementation may differ in some ways. The devref should<br>
be kept current with refactorings, etc. of the implementation.<br></blockquote><div><br></div><div>+1</div><div><br></div><div>Henry, that's very concisely written :)</div><div><br></div><div>I'd add, if X is purely a developer facing thing, then you can stop at 3.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class="HOEnZb"><font color="#888888"><br>
--<br>
Henry<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br></div></div>