Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Mathieu Rohon]

Hi all,

thanks for the explanation.
Can you also explain how does neutron team use blueprints? how it overlaps
with RFE bugs?

On Mon, Dec 7, 2015 at 6:40 PM, Sean M. Collins  wrote:

> On Mon, Dec 07, 2015 at 12:18:29PM EST, Carl Baldwin wrote:
> > On Fri, Dec 4, 2015 at 12:22 PM, Henry Gessau  wrote:
> > > 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.
> >
> > Henry, I was also impressed by how clearly you communicated this.
> > This ought to be included somewhere prominently in our
> > doc/source/policies/ or somewhere like that.
> >
>
> +1 for Henry's great answer, and +1 for Carl's suggestion!
>
> --
> Sean M. Collins
>
> __
> 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
>
__
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

Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Neil Jerram]

On 08/12/15 10:04, Mathieu Rohon wrote:
Hi all,

thanks for the explanation.
Can you also explain how does neutron team use blueprints? how it overlaps with 
RFE bugs?

Hi Mathieu,

This is all documented, in principle, at 
http://docs.openstack.org/developer/neutron/policies/blueprints.html.

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

Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Neil Jerram]

On 07/12/15 17:42, Sean M. Collins wrote:
> On Mon, Dec 07, 2015 at 12:18:29PM EST, Carl Baldwin wrote:
>> On Fri, Dec 4, 2015 at 12:22 PM, Henry Gessau  wrote:
>>> 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.
>> Henry, I was also impressed by how clearly you communicated this.
>> This ought to be included somewhere prominently in our
>> doc/source/policies/ or somewhere like that.
>>
> +1 for Henry's great answer, and +1 for Carl's suggestion!
>

I've suggested a change for this at
https://review.openstack.org/#/c/254669/.  Please take a look.

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

Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Mike Spreitzer]

> 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

Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Sean M. Collins]

On Tue, Dec 08, 2015 at 09:03:10AM EST, Mike Spreitzer wrote:
> 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?

Mike brings up a good point.

The one issue we need to content with is Google rankings. Specs are
published at specs.openstack.org - and are going to be found by people
looking to know more about an API. Especially when api-site and
networking API doc needs improvement.

Specs are a good starting point, but my hope would be that perhaps we go
back through the specs and add a note at the top pointing to the
maintained API documentation - once the feature has landed.

-- 
Sean M. Collins

__
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

Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Sean M. Collins]

On Mon, Dec 07, 2015 at 12:18:29PM EST, Carl Baldwin wrote:
> On Fri, Dec 4, 2015 at 12:22 PM, Henry Gessau  wrote:
> > 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.
> 
> Henry, I was also impressed by how clearly you communicated this.
> This ought to be included somewhere prominently in our
> doc/source/policies/ or somewhere like that.
> 

+1 for Henry's great answer, and +1 for Carl's suggestion!

-- 
Sean M. Collins

__
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

Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Carl Baldwin]

On Fri, Dec 4, 2015 at 12:22 PM, Henry Gessau  wrote:
> 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.

Henry, I was also impressed by how clearly you communicated this.
This ought to be included somewhere prominently in our
doc/source/policies/ or somewhere like that.

Carl

__
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

Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Neil Jerram]

On 04/12/15 19:24, Henry Gessau wrote:
> Sean M. Collins  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

Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Armando M.]

On 4 December 2015 at 11:22, Henry Gessau  wrote:

> Sean M. Collins  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.


>
> --
> Henry
>
> __
> 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
>
__
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

Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Akihiro Motoki]

2015-12-05 8:40 GMT+09:00 Armando M. :
>
>
> On 4 December 2015 at 11:22, Henry Gessau  wrote:
>>
>> Sean M. Collins  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-requ...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [neutron] Multiple locations for documentation of features

[Henry Gessau]

Sean M. Collins  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.

-- 
Henry

__
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

[openstack-dev] [neutron] Multiple locations for documentation of features

[Sean M. Collins]

Hi,

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?

-- 
Sean M. Collins

__
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