> From: Henry Gessau <ges...@gmail.com> > To: "OpenStack Development Mailing List (not for usage questions)" > <openstack-dev@lists.openstack.org> > Date: 12/04/2015 02:23 PM > Subject: Re: [openstack-dev] [neutron] Multiple locations for > documentation of features > > 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.
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? Regards, Mike
__________________________________________________________________________ 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
