Open Stack

2015-12-05 8:40 GMT+09:00 Armando M. <armamig at gmail.com>:
>
>
> 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
>> 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.

+1 too. Really well described.

I think DocImpact should be used for 4. OS docs
(even though DocImpact is filed to 'neutron' launchpad now)

3 devref can be added as part of a new feature patch.


>
>>
>>
>> --
>> Henry
>>
>> __________________________________________________________________________
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe: OpenStack-dev-request at 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>