Open Stack

On 04/12/15 19:24, Henry Gessau 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 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