2015-12-05 8:40 GMT+09:00 Armando M. <arma...@gmail.com>: > > > On 4 December 2015 at 11:22, Henry Gessau <ges...@gmail.com> wrote: >> >> Sean M. Collins <s...@coreitpro.com> wrote: >> > I've noticed that a lot of features are now being documented as RSTs >> > inside of devref. Like the following: >> > >> > https://review.openstack.org/#/c/251859/ >> > >> > But there are lots already present. Can someone point out to me what the >> > criteria is for these documents? I am a little confused about the >> > relationship between neutron-specs, RFE bugs, and some features being >> > documented in devref. Especially when a review includes the actual code, >> > then a new RST file in devref - wasn't that what specs were for? >> >> Here is how I would like to see things ending up: >> >> 1. RFE: "I want X" >> 2. Spec: "I plan to implement X like this" >> 3. devref: "How X is implemented and how to extend it" >> 4. OS docs: "API and guide for using X" >> >> Once X is implemented I don't want to have to go to 1 or 2 to find >> information >> on it. The devref may have a lot of content from the spec, but the spec is >> not >> maintained and the implementation may differ in some ways. The devref >> should >> be kept current with refactorings, etc. of the implementation. > > > +1 > > Henry, that's very concisely written :) > > I'd add, if X is purely a developer facing thing, then you can stop at 3.
+1 too. Really well described. I think DocImpact should be used for 4. OS docs (even though DocImpact is filed to 'neutron' launchpad now) 3 devref can be added as part of a new feature patch. > >> >> >> -- >> Henry >> >> __________________________________________________________________________ >> OpenStack Development Mailing List (not for usage questions) >> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev