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. > > -- > 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
