<tt><font size=2>> From: Henry Gessau <gessau@gmail.com></font></tt><br><tt><font size=2>> To: "OpenStack Development Mailing List
(not for usage questions)" <br>> <openstack-dev@lists.openstack.org></font></tt><br><tt><font size=2>> Date: 12/04/2015 02:23 PM</font></tt><br><tt><font size=2>> Subject: Re: [openstack-dev] [neutron] Multiple
locations for <br>> documentation of features</font></tt><br><tt><font size=2>> <br>> Sean M. Collins <sean@coreitpro.com> 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>> > </font></tt><a href=https://review.openstack.org/#/c/251859/><tt><font size=2>https://review.openstack.org/#/c/251859/</font></tt></a><tt><font size=2><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>> 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.</font></tt><br><br><tt><font size=2>Lots cheers from me too.  Let me add one thing:
"the spec is not maintained" is a remaining process bug.  A
spec by itself is a very useful thing.  It is the first thing to read
when trying to understand the implementation.  How about we resolve
that devref includes a maintained version of the spec?</font></tt><br><br><tt><font size=2>Regards,</font></tt><br><tt><font size=2>Mike</font></tt><BR>