[openstack-dev] [neutron] Multiple locations for documentation of features
armamig at gmail.com
Fri Dec 4 23:40:00 UTC 2015
On 4 December 2015 at 11:22, Henry Gessau <gessau at gmail.com> wrote:
> Sean M. Collins <sean at 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
> on it. The devref may have a lot of content from the spec, but the spec is
> maintained and the implementation may differ in some ways. The devref
> be kept current with refactorings, etc. of the implementation.
Henry, that's very concisely written :)
I'd add, if X is purely a developer facing thing, then you can stop at 3.
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OpenStack-dev