On 04/12/15 19:24, Henry Gessau 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. > FWIW, that's exactly how I'd see things too. It may be well that some of a spec's text is roughly suitable for later moving to a devref or OS doc, but even so it should be re-reviewed and edited for the new context, and for any details that changed during implementation. Regards, Neil __________________________________________________________________________ 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