Re: [openstack-dev] [docs][release][ptl] Adding docs to the release schedule

[Ian Cordasco]

-Original Message-
From: Brian Rosmaita <rosmaita.foss...@gmail.com>
Reply: OpenStack Development Mailing List (not for usage questions)
<openstack-dev@lists.openstack.org>
Date: March 2, 2017 at 16:55:10
To: OpenStack Development Mailing List (not for usage questions)
<openstack-dev@lists.openstack.org>
Subject:  Re: [openstack-dev] [docs][release][ptl] Adding docs to the
release schedule

> On 3/2/17 9:45 AM, Ian Cordasco wrote:
> > -Original Message-
> > From: Telles Nobrega
> > Reply: OpenStack Development Mailing List (not for usage questions)
> >
> > Date: March 2, 2017 at 08:01:29
> > To: OpenStack Development Mailing List (not for usage questions)
> >
> > Cc: openstack-d...@lists.openstack.org
> > Subject: Re: [openstack-dev] [docs][release][ptl] Adding docs to the
> > release schedule
> >
> >> I really believe that this idea will makes us work harder on keeping our
> >> docs in place and will make it for a better documented producted by release
> >> date.
> >> As shared before, I do believe that this is isn't easy and will demand a
> >> lot of effort from some teams, specially smaller teams with too much to do,
> >> but we from Sahara are on board with this approach and will try our best to
> >> do so.
> >
> > Most things worth doing are difficult. =) This seems to be one of
> > them. If deliverable teams really work together, they may end up in a
> > situation like Glance did this cycle where we kind of just sat on our
> > hands after RC-1 was tagged. That time *could* have been better spent
> > reviewing all of our documentation.
>
> At the risk of sounding defensive here, what exactly are you referring
> to? The api-ref [0], the dev docs in the glance repo [1], and the api
> docs in the glance-specs repo [2] all had patches up for review after RC-1.
>
> [0] https://review.openstack.org/#/c/426603/
> [1] https://review.openstack.org/#/c/429341/
> [2] https://review.openstack.org/#/c/426605/

I'm not trying to say we did something wrong. Just that there were
quite a few people who were focusing on things other than the Ocata
documentation. Hence the emphasis on "could". I think Glance came out
of Ocata looking great. I think we could look even better if we spent
more time on improving our documentation.

--
Ian Cordasco

__
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] [docs][release][ptl] Adding docs to the release schedule

[Brian Rosmaita]

On 3/2/17 9:45 AM, Ian Cordasco wrote:
> -Original Message-
> From: Telles Nobrega <tenob...@redhat.com>
> Reply: OpenStack Development Mailing List (not for usage questions)
> <openstack-dev@lists.openstack.org>
> Date: March 2, 2017 at 08:01:29
> To: OpenStack Development Mailing List (not for usage questions)
> <openstack-dev@lists.openstack.org>
> Cc: openstack-d...@lists.openstack.org <openstack-d...@lists.openstack.org>
> Subject:  Re: [openstack-dev] [docs][release][ptl] Adding docs to the
> release schedule
> 
>> I really believe that this idea will makes us work harder on keeping our
>> docs in place and will make it for a better documented producted by release
>> date.
>> As shared before, I do believe that this is isn't easy and will demand a
>> lot of effort from some teams, specially smaller teams with too much to do,
>> but we from Sahara are on board with this approach and will try our best to
>> do so.
> 
> Most things worth doing are difficult. =) This seems to be one of
> them. If deliverable teams really work together, they may end up in a
> situation like Glance did this cycle where we kind of just sat on our
> hands after RC-1 was tagged. That time *could* have been better spent
> reviewing all of our documentation.

At the risk of sounding defensive here, what exactly are you referring
to?  The api-ref [0], the dev docs in the glance repo [1], and the api
docs in the glance-specs repo [2] all had patches up for review after RC-1.

[0] https://review.openstack.org/#/c/426603/
[1] https://review.openstack.org/#/c/429341/
[2] https://review.openstack.org/#/c/426605/

> I know projects go sideways all the time. I think this was Glance's
> first cycle like this in a few cycles. But if we can make a habit of
> creating excellent release candidates, we can spend the intermediate
> time on documentation. I think that's a good compromise.
> 
> --
> Ian Cordasco
> 
> __
> 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] [docs][release][ptl] Adding docs to the release schedule

[Ian Cordasco]

-Original Message-
From: Telles Nobrega <tenob...@redhat.com>
Reply: OpenStack Development Mailing List (not for usage questions)
<openstack-dev@lists.openstack.org>
Date: March 2, 2017 at 08:01:29
To: OpenStack Development Mailing List (not for usage questions)
<openstack-dev@lists.openstack.org>
Cc: openstack-d...@lists.openstack.org <openstack-d...@lists.openstack.org>
Subject:  Re: [openstack-dev] [docs][release][ptl] Adding docs to the
release schedule

> I really believe that this idea will makes us work harder on keeping our
> docs in place and will make it for a better documented producted by release
> date.
> As shared before, I do believe that this is isn't easy and will demand a
> lot of effort from some teams, specially smaller teams with too much to do,
> but we from Sahara are on board with this approach and will try our best to
> do so.

Most things worth doing are difficult. =) This seems to be one of
them. If deliverable teams really work together, they may end up in a
situation like Glance did this cycle where we kind of just sat on our
hands after RC-1 was tagged. That time *could* have been better spent
reviewing all of our documentation.

I know projects go sideways all the time. I think this was Glance's
first cycle like this in a few cycles. But if we can make a habit of
creating excellent release candidates, we can spend the intermediate
time on documentation. I think that's a good compromise.

--
Ian Cordasco

__
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] [docs][release][ptl] Adding docs to the release schedule

[Telles Nobrega]

I really believe that this idea will makes us work harder on keeping our
docs in place and will make it for a better documented producted by release
date.
As shared before, I do believe that this is isn't easy and will demand a
lot of effort from some teams, specially smaller teams with too much to do,
but we from Sahara are on board with this approach and will try our best to
do so.

Thanks,

On Thu, Mar 2, 2017 at 7:33 AM Alexandra Settle <a.set...@outlook.com>
wrote:

>
>
>
>
> *From: *John Dickinson <m...@not.mn>
> *Reply-To: *"OpenStack Development Mailing List (not for usage
> questions)" <openstack-dev@lists.openstack.org>
> *Date: *Wednesday, March 1, 2017 at 11:50 PM
> *To: *OpenStack Development Mailing List <
> openstack-dev@lists.openstack.org>
> *Cc: *"openstack-d...@lists.openstack.org" <
> openstack-d...@lists.openstack.org>
> *Subject: *Re: [openstack-dev] [docs][release][ptl] Adding docs to the
> release schedule
>
>
>
> On 1 Mar 2017, at 10:07, Alexandra Settle wrote:
>
> On 3/1/17, 5:58 PM, "John Dickinson" <m...@not.mn> wrote:
>
>
>
> On 1 Mar 2017, at 9:52, Alexandra Settle wrote:
>
> > Hi everyone,
> >
> > I would like to propose that we introduce a “Review documentation”
> period on the release schedule.
> >
> > We would formulate it as a deadline, so that it fits in the schedule and
> making it coincide with the RC1 deadline.
> >
> > For projects that are not following the milestones, we would translate
> this new inclusion literally, so if you would like your project to be
> documented at docs.o.o, then doc must be introduced and reviewed one month
> before the branch is cut.
>
> Which docs are these? There are several different sets of docs that are
> hosted on docs.o.o that are managed within a project repo. Are you saying
> those won't get pushed to
> docs.o.o if they are patched within a month of the cycle release?
>
> The only sets of docs that are published on the docs.o.o site that are
> managed in project-specific repos is the project-specific installation
> guides. That management is entirely up to the team themselves, but I would
> like to push for the integration of a “documentation review” period to
> ensure that those teams are reviewing their docs in their own tree.
>
> This is a preferential suggestion, not a demand. I cannot make you review
> your documentation at any given period.
>
> The ‘month before’ that I refer to would be for introduction of
> documentation and a review period. I will not stop any documentation being
> pushed to the repo unless, of course, it is untested and breaks the
> installation process.
>
> There's the dev docs, the install guide, and the api reference. Each of
> these are published at docs.o.o, and each have elements that need to be
> up-to-date with a release.
>
> >
> > In the last week since we released Ocata, it has become increasingly
> apparent that the documentation was not updated from the development side.
> We were not aware of a lot of new enhancements, features, or major bug
> fixes for certain projects. This means we have released with
> incorrect/out-of-date documentation. This is not only an unfortunately bad
> reflection on our team, but on the project teams themselves.
> >
> > The new inclusion to the schedule may seem unnecessary, but a lot of
> people rely on this and the PTL drives milestones from this schedule.
> >
> > From our side, I endeavor to ensure our release managers are working
> harder to ping and remind doc liaisons and PTLs to ensure the documentation
> is appropriately updated and working to ensure this does not happen in the
> future.
>
> Overall, I really like the general concept here. It's very important to
> have good docs. Good docs start with the patch, and we should be
> encouraging the idea of "patch must have both tests and docs before
> landing".
>
> I’m glad to hear you think so :) this is entirely my thought process.
>
> On a personal note, though, I think I'll find this pretty tough. First,
> it's really hard for me to define when docs are "done", so it's hard to
> know that the docs are "right" at the time of release. Second, docs are
> built and published at each commit, so updating the docs "later, in a
> follow-on patch" is a simple thing to hope for and gives fast feedback,
> even after a release. (Of course the challenge is actually *doing* the
> patch later--see my previous paragraph.)
>
> So, unfortunately, I can give you no promise this was ever intended to be
> an easy inclusion. But in fairness, this is something teams should have
> already been doing.

Re: [openstack-dev] [docs][release][ptl] Adding docs to the release schedule

[Alexandra Settle]

From: John Dickinson <m...@not.mn>
Reply-To: "OpenStack Development Mailing List (not for usage questions)" 
<openstack-dev@lists.openstack.org>
Date: Wednesday, March 1, 2017 at 11:50 PM
To: OpenStack Development Mailing List <openstack-dev@lists.openstack.org>
Cc: "openstack-d...@lists.openstack.org" <openstack-d...@lists.openstack.org>
Subject: Re: [openstack-dev] [docs][release][ptl] Adding docs to the release 
schedule


On 1 Mar 2017, at 10:07, Alexandra Settle wrote:

On 3/1/17, 5:58 PM, "John Dickinson" <m...@not.mn> wrote:



On 1 Mar 2017, at 9:52, Alexandra Settle wrote:

> Hi everyone,
>
> I would like to propose that we introduce a “Review documentation” period on 
> the release schedule.
>
> We would formulate it as a deadline, so that it fits in the schedule and 
> making it coincide with the RC1 deadline.
>
> For projects that are not following the milestones, we would translate this 
> new inclusion literally, so if you would like your project to be documented 
> at docs.o.o, then doc must be introduced and reviewed one month before the 
> branch is cut.

Which docs are these? There are several different sets of docs that are hosted 
on docs.o.o that are managed within a project repo. Are you saying those won't 
get pushed to
docs.o.o if they are patched within a month of the cycle release?

The only sets of docs that are published on the docs.o.o site that are managed 
in project-specific repos is the project-specific installation guides. That 
management is entirely up to the team themselves, but I would like to push for 
the integration of a “documentation review” period to ensure that those teams 
are reviewing their docs in their own tree.

This is a preferential suggestion, not a demand. I cannot make you review your 
documentation at any given period.

The ‘month before’ that I refer to would be for introduction of documentation 
and a review period. I will not stop any documentation being pushed to the repo 
unless, of course, it is untested and breaks the installation process.

There's the dev docs, the install guide, and the api reference. Each of these 
are published at docs.o.o, and each have elements that need to be up-to-date 
with a release.

>
> In the last week since we released Ocata, it has become increasingly apparent 
> that the documentation was not updated from the development side. We were not 
> aware of a lot of new enhancements, features, or major bug fixes for certain 
> projects. This means we have released with incorrect/out-of-date 
> documentation. This is not only an unfortunately bad reflection on our team, 
> but on the project teams themselves.
>
> The new inclusion to the schedule may seem unnecessary, but a lot of people 
> rely on this and the PTL drives milestones from this schedule.
>
> From our side, I endeavor to ensure our release managers are working harder 
> to ping and remind doc liaisons and PTLs to ensure the documentation is 
> appropriately updated and working to ensure this does not happen in the 
> future.

Overall, I really like the general concept here. It's very important to have 
good docs. Good docs start with the patch, and we should be encouraging the 
idea of "patch must have both tests and docs before landing".

I’m glad to hear you think so :) this is entirely my thought process.

On a personal note, though, I think I'll find this pretty tough. First, it's 
really hard for me to define when docs are "done", so it's hard to know that 
the docs are "right" at the time of release. Second, docs are built and 
published at each commit, so updating the docs "later, in a follow-on patch" is 
a simple thing to hope for and gives fast feedback, even after a release. (Of 
course the challenge is actually doing the patch later--see my previous 
paragraph.)

So, unfortunately, I can give you no promise this was ever intended to be an 
easy inclusion. But in fairness, this is something teams should have already 
been doing.

However, as a PTL – you already have enough on your plate. We recommend a docs 
liaison that is not the PTL so that the individual is able to dedicate time to 
reviewing the documentation to the best of their ability. The docs being “done” 
= all new features that have a user impact are documented, and “right” = the 
user is able to install $project without major incident.

However, to reiterate my point before – we cannot force any team to do 
anything, but we would like to start actively encouraging the project teams to 
start seeing documentation as an important part of the release process, just as 
they would anything else.

“Treat docs like code” means so much more than just having a contribution 
process that is the same, it means treating the d

Re: [openstack-dev] [docs][release][ptl] Adding docs to the release schedule

[John Dickinson]

On 1 Mar 2017, at 10:07, Alexandra Settle wrote:

> On 3/1/17, 5:58 PM, "John Dickinson"  wrote:
>
>
>
> On 1 Mar 2017, at 9:52, Alexandra Settle wrote:
>
> > Hi everyone,
> >
> > I would like to propose that we introduce a “Review documentation” 
> period on the release schedule.
> >
> > We would formulate it as a deadline, so that it fits in the schedule 
> and making it coincide with the RC1 deadline.
> >
> > For projects that are not following the milestones, we would translate 
> this new inclusion literally, so if you would like your project to be 
> documented at docs.o.o, then doc must be introduced and reviewed one month 
> before the branch is cut.
>
> Which docs are these? There are several different sets of docs that are 
> hosted on docs.o.o that are managed within a project repo. Are you saying 
> those won't get pushed to
> docs.o.o if they are patched within a month of the cycle release?
>
> The only sets of docs that are published on the docs.o.o site that are 
> managed in project-specific repos is the project-specific installation 
> guides. That management is entirely up to the team themselves, but I would 
> like to push for the integration of a “documentation review” period to ensure 
> that those teams are reviewing their docs in their own tree.
>
> This is a preferential suggestion, not a demand. I cannot make you review 
> your documentation at any given period.
>
> The ‘month before’ that I refer to would be for introduction of documentation 
> and a review period. I will not stop any documentation being pushed to the 
> repo unless, of course, it is untested and breaks the installation process.

There's the dev docs, the install guide, and the api reference. Each of these 
are published at docs.o.o, and each have elements that need to be up-to-date 
with a release.

>
>
> >
> > In the last week since we released Ocata, it has become increasingly 
> apparent that the documentation was not updated from the development side. We 
> were not aware of a lot of new enhancements, features, or major bug fixes for 
> certain projects. This means we have released with incorrect/out-of-date 
> documentation. This is not only an unfortunately bad reflection on our team, 
> but on the project teams themselves.
> >
> > The new inclusion to the schedule may seem unnecessary, but a lot of 
> people rely on this and the PTL drives milestones from this schedule.
> >
> > From our side, I endeavor to ensure our release managers are working 
> harder to ping and remind doc liaisons and PTLs to ensure the documentation 
> is appropriately updated and working to ensure this does not happen in the 
> future.

Overall, I really like the general concept here. It's very important to have 
good docs. Good docs start with the patch, and we should be encouraging the 
idea of "patch must have both tests and docs before landing".

On a personal note, though, I think I'll find this pretty tough. First, it's 
really hard for me to define when docs are "done", so it's hard to know that 
the docs are "right" at the time of release. Second, docs are built and 
published at each commit, so updating the docs "later, in a follow-on patch" is 
a simple thing to hope for and gives fast feedback, even after a release. (Of 
course the challenge is actually *doing* the patch later--see my previous 
paragraph.)

> >
> > Thanks,
> >
> > Alex
>
>
> > 
> __
> > 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


signature.asc
Description: OpenPGP digital signature
__
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] [docs][release][ptl] Adding docs to the release schedule

[Alexandra Settle]

On 3/1/17, 5:58 PM, "John Dickinson"  wrote:



On 1 Mar 2017, at 9:52, Alexandra Settle wrote:

> Hi everyone,
>
> I would like to propose that we introduce a “Review documentation” period 
on the release schedule.
>
> We would formulate it as a deadline, so that it fits in the schedule and 
making it coincide with the RC1 deadline.
>
> For projects that are not following the milestones, we would translate 
this new inclusion literally, so if you would like your project to be 
documented at docs.o.o, then doc must be introduced and reviewed one month 
before the branch is cut.

Which docs are these? There are several different sets of docs that are 
hosted on docs.o.o that are managed within a project repo. Are you saying those 
won't get pushed to
docs.o.o if they are patched within a month of the cycle release?

The only sets of docs that are published on the docs.o.o site that are managed 
in project-specific repos is the project-specific installation guides. That 
management is entirely up to the team themselves, but I would like to push for 
the integration of a “documentation review” period to ensure that those teams 
are reviewing their docs in their own tree. 

This is a preferential suggestion, not a demand. I cannot make you review your 
documentation at any given period.

The ‘month before’ that I refer to would be for introduction of documentation 
and a review period. I will not stop any documentation being pushed to the repo 
unless, of course, it is untested and breaks the installation process. 


>
> In the last week since we released Ocata, it has become increasingly 
apparent that the documentation was not updated from the development side. We 
were not aware of a lot of new enhancements, features, or major bug fixes for 
certain projects. This means we have released with incorrect/out-of-date 
documentation. This is not only an unfortunately bad reflection on our team, 
but on the project teams themselves.
>
> The new inclusion to the schedule may seem unnecessary, but a lot of 
people rely on this and the PTL drives milestones from this schedule.
>
> From our side, I endeavor to ensure our release managers are working 
harder to ping and remind doc liaisons and PTLs to ensure the documentation is 
appropriately updated and working to ensure this does not happen in the future.
>
> Thanks,
>
> Alex


> __
> 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] [docs][release][ptl] Adding docs to the release schedule

[John Dickinson]

On 1 Mar 2017, at 9:52, Alexandra Settle wrote:

> Hi everyone,
>
> I would like to propose that we introduce a “Review documentation” period on 
> the release schedule.
>
> We would formulate it as a deadline, so that it fits in the schedule and 
> making it coincide with the RC1 deadline.
>
> For projects that are not following the milestones, we would translate this 
> new inclusion literally, so if you would like your project to be documented 
> at docs.o.o, then doc must be introduced and reviewed one month before the 
> branch is cut.

Which docs are these? There are several different sets of docs that are hosted 
on docs.o.o that are managed within a project repo. Are you saying those won't 
get pushed to docs.o.o if they are patched within a month of the cycle release?


>
> In the last week since we released Ocata, it has become increasingly apparent 
> that the documentation was not updated from the development side. We were not 
> aware of a lot of new enhancements, features, or major bug fixes for certain 
> projects. This means we have released with incorrect/out-of-date 
> documentation. This is not only an unfortunately bad reflection on our team, 
> but on the project teams themselves.
>
> The new inclusion to the schedule may seem unnecessary, but a lot of people 
> rely on this and the PTL drives milestones from this schedule.
>
> From our side, I endeavor to ensure our release managers are working harder 
> to ping and remind doc liaisons and PTLs to ensure the documentation is 
> appropriately updated and working to ensure this does not happen in the 
> future.
>
> Thanks,
>
> Alex


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


signature.asc
Description: OpenPGP digital signature
__
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] [docs][release][ptl] Adding docs to the release schedule

[Alexandra Settle]

Hi everyone,

I would like to propose that we introduce a “Review documentation” period on 
the release schedule.

We would formulate it as a deadline, so that it fits in the schedule and making 
it coincide with the RC1 deadline.

For projects that are not following the milestones, we would translate this new 
inclusion literally, so if you would like your project to be documented at 
docs.o.o, then doc must be introduced and reviewed one month before the branch 
is cut.

In the last week since we released Ocata, it has become increasingly apparent 
that the documentation was not updated from the development side. We were not 
aware of a lot of new enhancements, features, or major bug fixes for certain 
projects. This means we have released with incorrect/out-of-date documentation. 
This is not only an unfortunately bad reflection on our team, but on the 
project teams themselves.

The new inclusion to the schedule may seem unnecessary, but a lot of people 
rely on this and the PTL drives milestones from this schedule.

From our side, I endeavor to ensure our release managers are working harder to 
ping and remind doc liaisons and PTLs to ensure the documentation is 
appropriately updated and working to ensure this does not happen in the future.

Thanks,

Alex

__
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