Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[ZhiQiang Fan]

Agree.

Install guide is just a start/example, concentrate is better than cover
all, for more services we can just provide a good place to let them
discoverable, and lfor arger scale, we should use advanced tools such as
puppet and ansible

On Mon, Apr 4, 2016 at 6:12 PM, Thierry Carrez 
wrote:

> Doug Hellmann wrote:
>
>> [...]
>>> We would love to add all sufficiently mature projects to the installation
>>> guide because it increases visibility and adoption by operators, but we
>>> lack resources to develop a source installation mechanism that retains as
>>> much simplicity as possible for our audience.
>>>
>>
>> I think it would be a big mistake to try to create one guide for
>> installing all OpenStack projects. As you say, testing what we have
>> now is already a monumental task and impedes your ability to make
>> changes.  Adding more projects, with ever more dependencies and
>> configuration issues to the work the same team is doing would bury
>> the current documentation team. So I think focusing on the DefCore
>> list, or even a smaller list of projects with tight installation
>> integration requirements, makes sense for the team currently producing
>> the installation guide.
>>
>
> Yes, the base install guide should ideally serve as a reference to reach
> that first step where you have all the underlying services (MySQL, Rabbit)
> and a base set of functionality (starterkit:compute ?) installed and
> working. That is where we need high-quality, proactively-checked, easy to
> understand content.
>
> Then additional guides (ideally produced by each project team with tooling
> and mentoring from the docs team) can pick up from that base first step,
> assuming their users have completed that first step successfully.
>
> --
> Thierry Carrez (ttx)
>
>
> __
> 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] Our Install Guides Only Cover Defcore - What about big tent?

[Lana Brindley]

Hi Jonathan,

It's all good, this is actually unrelated to the larger changes proposed for 
Newton, but more about a late change that was proposed for Kilo. 

HTH,
L 

On 14/04/16 03:59, Jonathan D. Proulx wrote:
> On Wed, Apr 13, 2016 at 01:52:38PM -0400, Jonathan D. Proulx wrote:
> 
> :I've not been following this thread at all so appologies if I'm
> :confused.
> 
>  reading follow up emails relating to timing of various submissions, I
>  back away slowly clearly not having all the context on this one.
> 
> -Jon
> 
> __
> 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
> 

-- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com



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] Our Install Guides Only Cover Defcore - What about big tent?

[Amrith Kumar]

Andreas,

Thanks for your email. I am aware of the reviews you describe below but I was 
still under the impression that the status from the email on openstack-docs 
(Mitaka Install Guide testing) [1] and [2] were still valid.

The understanding I had from those email threads is that the door hadn't yet 
closed. But I'll defer to the doc team; I think you understand the motivation 
for my request, and I respect (and fully admit that I don't understand) the 
complexities involved in releasing documentation.

I trust that if it is at all possible, you will accommodate the request. Of 
your options below, I would request #2 if at all possible.

Thanks,

-amrith


[1] http://lists.openstack.org/pipermail/openstack-docs/2016-March/008385.html
[2] http://lists.openstack.org/pipermail/openstack-docs/2016-March/008387.html



> -Original Message-
> From: Andreas Jaeger [mailto:a...@suse.com]
> Sent: Wednesday, April 13, 2016 1:46 PM
> To: Amrith Kumar <amr...@tesora.com>; OpenStack Development Mailing List
> (not for usage questions) <openstack-dev@lists.openstack.org>
> Cc: mkassaw...@gmail.com; Lana Brindley <openst...@lanabrindley.com>; Mike
> Perez <m...@openstack.org>; openstack-d...@lists.openstack.org
> Subject: Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore
> - What about big tent?
> 
> On 04/13/2016 07:17 PM, Amrith Kumar wrote:
> > Andreas, Lana, Mike, Matt, and others who've been active on this
> > thread,
> >
> > I've been following this conversation about installation documentation
> and core vs. non-core projects from afar and was under the impression that
> the changes being proposed would take effect for Newton and moving
> forward.
> >
> > Today I was informed that after a lot of effort and testing, the
> installation guide for Trove/Mitaka which is ready and up for review[1]
> has been placed on hold pending the outcome of your discussions in Austin.
> 
> > The documentation that is now available and ready for review is for the
> Mitaka series and should not, I believe, be held up because there is now a
> proposal afoot to put non-core project installation guides somewhere else.
> If we choose to do that, that's a conversation for Newton, I believe, and
> I believe that the Trove installation guide for Mitaka should be
> considered for inclusion along with the other Mitaka documentation.
> 
> Amrith, I'm a bit surprised by this email and request. So, let me give
> some more context.
> 
> There's a spec out:
> https://review.openstack.org/#/c/290053 for this work which came very
> late. Bogdan asked on the 23rd of March, and I commented on the spec with
> -1 on the 27th of March that this is a post-Mitaka topic. Then, on the
> 29th of March, your referenced change gets submitted -without any followup
> discussion on the spec.
> 
> Would you have taken a code change under these conditions for trove
> itself?
> 
> While I applaud your team's work, the documentation team also needs to
> review content you propose for consistency - and that takes time. We're
> still flashing out some details for some of the guides for Mitaka.
> 
> > The lack of installation guides for a project is a serious challenge for
> deployers and users, and much work has been expended getting the Trove
> documentation ready and thoroughly tested on Ubuntu, RDO and SUSE.
> >
> > I'm therefore requesting that the doc team consider this set of
> documentation for the Mitaka series and make it available with the other
> install guides for other projects after it has been reviewed, and not hold
> it subject to the outcome of some Newton focused discussion that is to
> happen in Austin.
> 
> I'm glad about the work the team has done and will not block this going in
> on my own. IMHO think we have the following options:
> 
> 1) Wait until Austin and speed track this change afterwards based on the
> outcome of the discussion there if possible.
> 2) Take the change in with the explicit understanding that it might be
> taken out again based on the general Install Guide discussion.
> 3) Do nothing for Mitaka.
> 
> I'm happy to take my -2 away from the change after the spec has been
> approved and we've decided which of the options  to take - and for that I
> defer to Lana and Matt.
> 
> So, let's discuss how to move forward on the documentation list with the
> docs team and see what they suggest,
> 
> Andreas
> 
> > Thanks,
> >
> > -amrith
> >
> >
> > [1] https://review.openstack.org/#/c/298929/
> >
> >> -----Original Message-
> >> From: Andreas Jaeger [mailto:a...@suse.com]
> >> Sent: Monday, April 04, 2016 2:42 PM
> >> To: OpenStack Devel

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Jonathan D. Proulx]

On Wed, Apr 13, 2016 at 01:52:38PM -0400, Jonathan D. Proulx wrote:

:I've not been following this thread at all so appologies if I'm
:confused.

 reading follow up emails relating to timing of various submissions, I
 back away slowly clearly not having all the context on this one.

-Jon

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Jonathan D. Proulx]

On Wed, Apr 13, 2016 at 05:17:18PM +, Amrith Kumar wrote:

:Today I was informed that after a lot of effort and testing, the installation 
guide for Trove/Mitaka which is ready and up for review[1] has been placed on 
hold pending the outcome of your discussions in Austin.

I've not been following this thread at all so appologies if I'm
confused.

As an operator and a (former? it's been a while) docs contributor
seems to me that the Newton proposal makes sense (given my breif
reading).  I don't see why Mitaka docs that are already written and
tested should be help up on that though, seems the point of coordinated
reseases is so other can rely on major structures being stable through
them.

My $0.02,
-Jon

:
:The documentation that is now available and ready for review is for the Mitaka 
series and should not, I believe, be held up because there is now a proposal 
afoot to put non-core project installation guides somewhere else. If we choose 
to do that, that's a conversation for Newton, I believe, and I believe that the 
Trove installation guide for Mitaka should be considered for inclusion along 
with the other Mitaka documentation.
:
:The lack of installation guides for a project is a serious challenge for 
deployers and users, and much work has been expended getting the Trove 
documentation ready and thoroughly tested on Ubuntu, RDO and SUSE.
:
:I'm therefore requesting that the doc team consider this set of documentation 
for the Mitaka series and make it available with the other install guides for 
other projects after it has been reviewed, and not hold it subject to the 
outcome of some Newton focused discussion that is to happen in Austin.
:
:Thanks,
:
:-amrith
:
:
:[1] https://review.openstack.org/#/c/298929/
:
:> -Original Message-
:> From: Andreas Jaeger [mailto:a...@suse.com]
:> Sent: Monday, April 04, 2016 2:42 PM
:> To: OpenStack Development Mailing List (not for usage questions)
:> <openstack-dev@lists.openstack.org>
:> Subject: Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore
:> - What about big tent?
:> 
:> On 04/04/2016 12:12 PM, Thierry Carrez wrote:
:> > Doug Hellmann wrote:
:> >>> [...]
:> >>> We would love to add all sufficiently mature projects to the
:> >>> installation guide because it increases visibility and adoption by
:> >>> operators, but we lack resources to develop a source installation
:> >>> mechanism that retains as much simplicity as possible for our
:> >>> audience.
:> >>
:> >> I think it would be a big mistake to try to create one guide for
:> >> installing all OpenStack projects. As you say, testing what we have
:> >> now is already a monumental task and impedes your ability to make
:> >> changes.  Adding more projects, with ever more dependencies and
:> >> configuration issues to the work the same team is doing would bury
:> >> the current documentation team. So I think focusing on the DefCore
:> >> list, or even a smaller list of projects with tight installation
:> >> integration requirements, makes sense for the team currently
:> >> producing the installation guide.
:> >
:> > Yes, the base install guide should ideally serve as a reference to
:> > reach that first step where you have all the underlying services
:> > (MySQL,
:> > Rabbit) and a base set of functionality (starterkit:compute ?)
:> > installed and working. That is where we need high-quality,
:> > proactively-checked, easy to understand content.
:> >
:> > Then additional guides (ideally produced by each project team with
:> > tooling and mentoring from the docs team) can pick up from that base
:> > first step, assuming their users have completed that first step
:> > successfully.
:> >
:> 
:> Fully agreed.
:> 
:> I just wrote a first draft spec for all of this and look forward to
:> reviews.
:> 
:> I'll enhance some more tomorrow, might copy a bit from above (saw this too
:> late).
:> 
:> https://review.openstack.org/301284
:> 
:> Andreas
:> --
:>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
:>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
:>GF: Felix Imendörffer, Jane Smithard, Graham Norton,
:>HRB 21284 (AG Nürnberg)
:> GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
:> 
:> 
:> __
:> 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

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Andreas Jaeger]

On 04/13/2016 07:17 PM, Amrith Kumar wrote:
> Andreas, Lana, Mike, Matt, and others who've been active on this thread,
> 
> I've been following this conversation about installation documentation and 
> core vs. non-core projects from afar and was under the impression that the 
> changes being proposed would take effect for Newton and moving forward.
> 
> Today I was informed that after a lot of effort and testing, the installation 
> guide for Trove/Mitaka which is ready and up for review[1] has been placed on 
> hold pending the outcome of your discussions in Austin.

> The documentation that is now available and ready for review is for the 
> Mitaka series and should not, I believe, be held up because there is now a 
> proposal afoot to put non-core project installation guides somewhere else. If 
> we choose to do that, that's a conversation for Newton, I believe, and I 
> believe that the Trove installation guide for Mitaka should be considered for 
> inclusion along with the other Mitaka documentation.

Amrith, I'm a bit surprised by this email and request. So, let me give
some more context.

There's a spec out:
https://review.openstack.org/#/c/290053 for this work which came very
late. Bogdan asked on the 23rd of March, and I commented on the spec
with -1 on the 27th of March that this is a post-Mitaka topic. Then, on
the 29th of March, your referenced change gets submitted -without any
followup discussion on the spec.

Would you have taken a code change under these conditions for trove itself?

While I applaud your team's work, the documentation team also needs to
review content you propose for consistency - and that takes time. We're
still flashing out some details for some of the guides for Mitaka.

> The lack of installation guides for a project is a serious challenge for 
> deployers and users, and much work has been expended getting the Trove 
> documentation ready and thoroughly tested on Ubuntu, RDO and SUSE.
> 
> I'm therefore requesting that the doc team consider this set of documentation 
> for the Mitaka series and make it available with the other install guides for 
> other projects after it has been reviewed, and not hold it subject to the 
> outcome of some Newton focused discussion that is to happen in Austin.

I'm glad about the work the team has done and will not block this going
in on my own. IMHO think we have the following options:

1) Wait until Austin and speed track this change afterwards based on the
outcome of the discussion there if possible.
2) Take the change in with the explicit understanding that it might be
taken out again based on the general Install Guide discussion.
3) Do nothing for Mitaka.

I'm happy to take my -2 away from the change after the spec has been
approved and we've decided which of the options  to take - and for that
I defer to Lana and Matt.

So, let's discuss how to move forward on the documentation list with the
docs team and see what they suggest,

Andreas

> Thanks,
> 
> -amrith
> 
> 
> [1] https://review.openstack.org/#/c/298929/
> 
>> -Original Message-
>> From: Andreas Jaeger [mailto:a...@suse.com]
>> Sent: Monday, April 04, 2016 2:42 PM
>> To: OpenStack Development Mailing List (not for usage questions)
>> <openstack-dev@lists.openstack.org>
>> Subject: Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore
>> - What about big tent?
>>
>> On 04/04/2016 12:12 PM, Thierry Carrez wrote:
>>> Doug Hellmann wrote:
>>>>> [...]
>>>>> We would love to add all sufficiently mature projects to the
>>>>> installation guide because it increases visibility and adoption by
>>>>> operators, but we lack resources to develop a source installation
>>>>> mechanism that retains as much simplicity as possible for our
>>>>> audience.
>>>>
>>>> I think it would be a big mistake to try to create one guide for
>>>> installing all OpenStack projects. As you say, testing what we have
>>>> now is already a monumental task and impedes your ability to make
>>>> changes.  Adding more projects, with ever more dependencies and
>>>> configuration issues to the work the same team is doing would bury
>>>> the current documentation team. So I think focusing on the DefCore
>>>> list, or even a smaller list of projects with tight installation
>>>> integration requirements, makes sense for the team currently
>>>> producing the installation guide.
>>>
>>> Yes, the base install guide should ideally serve as a reference to
>>> reach that first step where you have all the underlying services
>>> (MySQL,
>>> Rabbit) and a base set of functionality (starterkit:com

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Amrith Kumar]

Andreas, Lana, Mike, Matt, and others who've been active on this thread,

I've been following this conversation about installation documentation and core 
vs. non-core projects from afar and was under the impression that the changes 
being proposed would take effect for Newton and moving forward.

Today I was informed that after a lot of effort and testing, the installation 
guide for Trove/Mitaka which is ready and up for review[1] has been placed on 
hold pending the outcome of your discussions in Austin.

The documentation that is now available and ready for review is for the Mitaka 
series and should not, I believe, be held up because there is now a proposal 
afoot to put non-core project installation guides somewhere else. If we choose 
to do that, that's a conversation for Newton, I believe, and I believe that the 
Trove installation guide for Mitaka should be considered for inclusion along 
with the other Mitaka documentation.

The lack of installation guides for a project is a serious challenge for 
deployers and users, and much work has been expended getting the Trove 
documentation ready and thoroughly tested on Ubuntu, RDO and SUSE.

I'm therefore requesting that the doc team consider this set of documentation 
for the Mitaka series and make it available with the other install guides for 
other projects after it has been reviewed, and not hold it subject to the 
outcome of some Newton focused discussion that is to happen in Austin.

Thanks,

-amrith


[1] https://review.openstack.org/#/c/298929/

> -Original Message-
> From: Andreas Jaeger [mailto:a...@suse.com]
> Sent: Monday, April 04, 2016 2:42 PM
> To: OpenStack Development Mailing List (not for usage questions)
> <openstack-dev@lists.openstack.org>
> Subject: Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore
> - What about big tent?
> 
> On 04/04/2016 12:12 PM, Thierry Carrez wrote:
> > Doug Hellmann wrote:
> >>> [...]
> >>> We would love to add all sufficiently mature projects to the
> >>> installation guide because it increases visibility and adoption by
> >>> operators, but we lack resources to develop a source installation
> >>> mechanism that retains as much simplicity as possible for our
> >>> audience.
> >>
> >> I think it would be a big mistake to try to create one guide for
> >> installing all OpenStack projects. As you say, testing what we have
> >> now is already a monumental task and impedes your ability to make
> >> changes.  Adding more projects, with ever more dependencies and
> >> configuration issues to the work the same team is doing would bury
> >> the current documentation team. So I think focusing on the DefCore
> >> list, or even a smaller list of projects with tight installation
> >> integration requirements, makes sense for the team currently
> >> producing the installation guide.
> >
> > Yes, the base install guide should ideally serve as a reference to
> > reach that first step where you have all the underlying services
> > (MySQL,
> > Rabbit) and a base set of functionality (starterkit:compute ?)
> > installed and working. That is where we need high-quality,
> > proactively-checked, easy to understand content.
> >
> > Then additional guides (ideally produced by each project team with
> > tooling and mentoring from the docs team) can pick up from that base
> > first step, assuming their users have completed that first step
> > successfully.
> >
> 
> Fully agreed.
> 
> I just wrote a first draft spec for all of this and look forward to
> reviews.
> 
> I'll enhance some more tomorrow, might copy a bit from above (saw this too
> late).
> 
> https://review.openstack.org/301284
> 
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>HRB 21284 (AG Nürnberg)
> GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
> 
> 
> __
> 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] Our Install Guides Only Cover Defcore - What about big tent?

[Kenny Johnston]

On Mon, Apr 4, 2016 at 1:41 PM, Andreas Jaeger  wrote:

> On 04/04/2016 12:12 PM, Thierry Carrez wrote:
> > Doug Hellmann wrote:
> >>> [...]
> >>> We would love to add all sufficiently mature projects to the
> >>> installation
> >>> guide because it increases visibility and adoption by operators, but we
> >>> lack resources to develop a source installation mechanism that
> >>> retains as
> >>> much simplicity as possible for our audience.
> >>
> >> I think it would be a big mistake to try to create one guide for
> >> installing all OpenStack projects. As you say, testing what we have
> >> now is already a monumental task and impedes your ability to make
> >> changes.  Adding more projects, with ever more dependencies and
> >> configuration issues to the work the same team is doing would bury
> >> the current documentation team. So I think focusing on the DefCore
> >> list, or even a smaller list of projects with tight installation
> >> integration requirements, makes sense for the team currently producing
> >> the installation guide.
> >
> > Yes, the base install guide should ideally serve as a reference to reach
> > that first step where you have all the underlying services (MySQL,
> > Rabbit) and a base set of functionality (starterkit:compute ?) installed
> > and working. That is where we need high-quality, proactively-checked,
> > easy to understand content.
> >
> > Then additional guides (ideally produced by each project team with
> > tooling and mentoring from the docs team) can pick up from that base
> > first step, assuming their users have completed that first step
> > successfully.
> >
>
> Fully agreed.
>
> I just wrote a first draft spec for all of this and look forward to
> reviews.
>
> I'll enhance some more tomorrow, might copy a bit from above (saw this
> too late).
>
> https://review.openstack.org/301284
>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>HRB 21284 (AG Nürnberg)
> GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
> __
> 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
>

I commented on the review, but is an alternative solution to appropriately
rename the Install Guide to something like "OpenStack Proof of Concept
Guide" or "OpenStack Starter Kit Guide" and then create the centralized
docs.o.o/install-guides that references both project-specific and
deployment-project install guides?

These guides could then offer more flexibility in install options and
advice.

-- 
Kenny Johnston | freenode:kencjohnston | @kencjohnston
__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Andreas Jaeger]

On 04/04/2016 12:12 PM, Thierry Carrez wrote:
> Doug Hellmann wrote:
>>> [...]
>>> We would love to add all sufficiently mature projects to the
>>> installation
>>> guide because it increases visibility and adoption by operators, but we
>>> lack resources to develop a source installation mechanism that
>>> retains as
>>> much simplicity as possible for our audience.
>>
>> I think it would be a big mistake to try to create one guide for
>> installing all OpenStack projects. As you say, testing what we have
>> now is already a monumental task and impedes your ability to make
>> changes.  Adding more projects, with ever more dependencies and
>> configuration issues to the work the same team is doing would bury
>> the current documentation team. So I think focusing on the DefCore
>> list, or even a smaller list of projects with tight installation
>> integration requirements, makes sense for the team currently producing
>> the installation guide.
> 
> Yes, the base install guide should ideally serve as a reference to reach
> that first step where you have all the underlying services (MySQL,
> Rabbit) and a base set of functionality (starterkit:compute ?) installed
> and working. That is where we need high-quality, proactively-checked,
> easy to understand content.
> 
> Then additional guides (ideally produced by each project team with
> tooling and mentoring from the docs team) can pick up from that base
> first step, assuming their users have completed that first step
> successfully.
> 

Fully agreed.

I just wrote a first draft spec for all of this and look forward to reviews.

I'll enhance some more tomorrow, might copy a bit from above (saw this
too late).

https://review.openstack.org/301284

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Thierry Carrez]

Doug Hellmann wrote:

[...]
We would love to add all sufficiently mature projects to the installation
guide because it increases visibility and adoption by operators, but we
lack resources to develop a source installation mechanism that retains as
much simplicity as possible for our audience.


I think it would be a big mistake to try to create one guide for
installing all OpenStack projects. As you say, testing what we have
now is already a monumental task and impedes your ability to make
changes.  Adding more projects, with ever more dependencies and
configuration issues to the work the same team is doing would bury
the current documentation team. So I think focusing on the DefCore
list, or even a smaller list of projects with tight installation
integration requirements, makes sense for the team currently producing
the installation guide.


Yes, the base install guide should ideally serve as a reference to reach 
that first step where you have all the underlying services (MySQL, 
Rabbit) and a base set of functionality (starterkit:compute ?) installed 
and working. That is where we need high-quality, proactively-checked, 
easy to understand content.


Then additional guides (ideally produced by each project team with 
tooling and mentoring from the docs team) can pick up from that base 
first step, assuming their users have completed that first step 
successfully.


--
Thierry Carrez (ttx)

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Doug Hellmann]

Excerpts from Matt Kassawara's message of 2016-04-01 12:38:02 -0600:
> Hi,
> 
> I didn't see this e-mail until now because I'm busy trying to update and
> test the installation guide in time for the Mitaka release. As a primary
> contributor to the installation guide for about six releases including
> restructuring it a couple of times, I think I can explain why we do what we
> do.
> 
> First, a little history about the guide...
> 
> The installation guide often provides the first experience for people
> trying OpenStack. Thus, the guide should provide not just a good
> experience, but a great experience. We can all agree on wanting more
> adoption of OpenStack. For many people, launching an instance and being
> able to access it feels like summiting a mountain. My first experience with
> OpenStack involved nearly a month of trying to install Grizzly with neutron
> for evaluation purposes using the installation guide. It didn't work.
> Looking at various support channels such as IRC and ask.openstack.org, most
> people were stuck at the same place without any answers. I finally
> determined that nova lacked the configuration telling it to use neutron for
> networking, so it kept attempting to build nova networks when those
> components didn't exist. I opened a bug and someone fixed it. Shortly
> thereafter, I began addressing the seemingly infinite number of
> installation guide bugs. However, the cycle of frustration was beginning to
> repeat itself with Havana. The reactive method of finding a problem,
> opening a bug, and waiting for a patch simply wasn't working for our
> audience of potential operators, not developers, that just expect it to
> work.
> 
> So, I proposed changing the guide from reactive to proactive. In other
> words, we update and test the guide prior to release for every distribution
> it supports. We began this approach with Icehouse and saw a decrease in
> bugs and frustration. Furthermore, when assisting people through various
> support channels, we could more easily determine whether the problem was a
> just a typo or a problem with the guide. However, proactively maintaining
> the guide put a significant burden on the contributors. Gone were the days
> of "fire-and-forget" patches. Almost all patches require actual testing,
> sometimes across several distributions. Updating the guide for the next
> release requires performing full installations, often several times per
> distribution, until we can successfully install and test all services
> without deviating from the instructions. A considerable amount of work,
> especially about a month before release when contributors who involve
> themselves in other projects are also busy trying to release those
> projects. Thus, the installation guide has seen a decrease in contributions
> making it increasingly difficult to update and test for each release.
> Furthermore, the installation guide receives little, if any, support from
> most projects including "core" projects. Even if those projects know about
> the installation guide, most assume that the documentation team magically
> updates it for every release to deploy each service in a basic fashion
> accounting for configuration changes and recommendations. From the
> perspective of a project developer, those updates probably seem simple.
> Just read the code, track patches, and maybe attend some meetings, right?
> From the perspective of installation guide contributors, we can't involve
> ourselves that deeply in one project let alone nearly ten projects. Imagine
> us trying to consider big tent projects? We have begged projects for years
> to provide resources for maintaining the installation guide. If nothing
> else, provide some notes on an etherpad indicating what we should change.
> At this point in the game, we shouldn't have to resort to deprecation
> messages or gate job configurations to determine how to deploy a service.
> 
> Regarding use of distribution packages instead of source...
> 
> The guide uses distribution packages instead of source because our audience
> is usually familiar with them and they eliminate a significant number of
> steps in an already complex and often overwhelming process. For example,
> packages manage dependencies and provide init scripts. The installation
> guide teaches our audience how to deploy the most common OpenStack services
> for evaluation purposes. For example, our audience quickly learns that each
> service typically depends on keystone, a database, and a message queue.
> After getting comfortable with the installation process, we recommend
> implementing redundancy/security on top of a basic installation and
> eventually tooling for a production deployment.
> 
> Distribution packages aren't perfect by any means. First, they usually lag
> the upstream release cycle by several weeks which forces us to update and
> test changes using milestones, sometimes not even the last "feature-freeze"
> milestone, after the first release candidate 

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Matt Kassawara]

Hi,

I didn't see this e-mail until now because I'm busy trying to update and
test the installation guide in time for the Mitaka release. As a primary
contributor to the installation guide for about six releases including
restructuring it a couple of times, I think I can explain why we do what we
do.

First, a little history about the guide...

The installation guide often provides the first experience for people
trying OpenStack. Thus, the guide should provide not just a good
experience, but a great experience. We can all agree on wanting more
adoption of OpenStack. For many people, launching an instance and being
able to access it feels like summiting a mountain. My first experience with
OpenStack involved nearly a month of trying to install Grizzly with neutron
for evaluation purposes using the installation guide. It didn't work.
Looking at various support channels such as IRC and ask.openstack.org, most
people were stuck at the same place without any answers. I finally
determined that nova lacked the configuration telling it to use neutron for
networking, so it kept attempting to build nova networks when those
components didn't exist. I opened a bug and someone fixed it. Shortly
thereafter, I began addressing the seemingly infinite number of
installation guide bugs. However, the cycle of frustration was beginning to
repeat itself with Havana. The reactive method of finding a problem,
opening a bug, and waiting for a patch simply wasn't working for our
audience of potential operators, not developers, that just expect it to
work.

So, I proposed changing the guide from reactive to proactive. In other
words, we update and test the guide prior to release for every distribution
it supports. We began this approach with Icehouse and saw a decrease in
bugs and frustration. Furthermore, when assisting people through various
support channels, we could more easily determine whether the problem was a
just a typo or a problem with the guide. However, proactively maintaining
the guide put a significant burden on the contributors. Gone were the days
of "fire-and-forget" patches. Almost all patches require actual testing,
sometimes across several distributions. Updating the guide for the next
release requires performing full installations, often several times per
distribution, until we can successfully install and test all services
without deviating from the instructions. A considerable amount of work,
especially about a month before release when contributors who involve
themselves in other projects are also busy trying to release those
projects. Thus, the installation guide has seen a decrease in contributions
making it increasingly difficult to update and test for each release.
Furthermore, the installation guide receives little, if any, support from
most projects including "core" projects. Even if those projects know about
the installation guide, most assume that the documentation team magically
updates it for every release to deploy each service in a basic fashion
accounting for configuration changes and recommendations. From the
perspective of a project developer, those updates probably seem simple.
Just read the code, track patches, and maybe attend some meetings, right?
>From the perspective of installation guide contributors, we can't involve
ourselves that deeply in one project let alone nearly ten projects. Imagine
us trying to consider big tent projects? We have begged projects for years
to provide resources for maintaining the installation guide. If nothing
else, provide some notes on an etherpad indicating what we should change.
At this point in the game, we shouldn't have to resort to deprecation
messages or gate job configurations to determine how to deploy a service.

Regarding use of distribution packages instead of source...

The guide uses distribution packages instead of source because our audience
is usually familiar with them and they eliminate a significant number of
steps in an already complex and often overwhelming process. For example,
packages manage dependencies and provide init scripts. The installation
guide teaches our audience how to deploy the most common OpenStack services
for evaluation purposes. For example, our audience quickly learns that each
service typically depends on keystone, a database, and a message queue.
After getting comfortable with the installation process, we recommend
implementing redundancy/security on top of a basic installation and
eventually tooling for a production deployment.

Distribution packages aren't perfect by any means. First, they usually lag
the upstream release cycle by several weeks which forces us to update and
test changes using milestones, sometimes not even the last "feature-freeze"
milestone, after the first release candidate appears upstream. Next, they
sometimes contain bugs and packagers seldom contribute resources to triage
and address them which forces us to implement workarounds that can confuse
or distract our audience. Finally, and 

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Doug Hellmann]

On Wed, Mar 30, 2016, at 03:37 AM, Thomas Goirand wrote:
> On 03/29/2016 08:33 PM, Doug Hellmann wrote:
> > If the core doc team isn't able to help you maintain it, maybe it's a
> > candidate for a separate guide, just like we're discussing for projects
> > that aren't part of the DefCore set included in the main guide.
> > 
> > Doug
> 
> This is exactly what I don't want. Only installing the packages
> themselves is different. Like for example, "apt-get install foo" and
> answering a few debconf prompts is often enough to get packages to work,
> without the need for manual setup of dbs, or rabbitMQ credentials. But
> that's maybe 20% of the install-guide, and the rest of is left
> untouched, with no conditionals. For example the description of the
> services, testing them after install, etc. Having a separated guide
> would mean that someone would be left to write a full install-guide from
> scratch, alone. That isn't desirable.
> 
> It is also my hope that the packaging on upstream infra will get going.
> If it does, it will make more sense to get the Debian guide up to speed,
> and probably there will be more contributors.

Perhaps that common content should be a separate guide? I don't know the
best solution, but I don't think requiring any one team to keep up with
*everything* needed to install all projects on all platforms using all
available tools is the right approach. See Conway's Law.

Doug

> 
> Cheers,
> 
> Thomas Goirand (zigo)
> 
> 
> __
> 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] Our Install Guides Only Cover Defcore - What about big tent?

[Thomas Goirand]

On 03/29/2016 08:33 PM, Doug Hellmann wrote:
> If the core doc team isn't able to help you maintain it, maybe it's a
> candidate for a separate guide, just like we're discussing for projects
> that aren't part of the DefCore set included in the main guide.
> 
> Doug

This is exactly what I don't want. Only installing the packages
themselves is different. Like for example, "apt-get install foo" and
answering a few debconf prompts is often enough to get packages to work,
without the need for manual setup of dbs, or rabbitMQ credentials. But
that's maybe 20% of the install-guide, and the rest of is left
untouched, with no conditionals. For example the description of the
services, testing them after install, etc. Having a separated guide
would mean that someone would be left to write a full install-guide from
scratch, alone. That isn't desirable.

It is also my hope that the packaging on upstream infra will get going.
If it does, it will make more sense to get the Debian guide up to speed,
and probably there will be more contributors.

Cheers,

Thomas Goirand (zigo)


__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Doug Hellmann]

Excerpts from Thomas Goirand's message of 2016-03-29 13:37:14 +0200:
> On 03/29/2016 11:56 AM, Neil Jerram wrote:
> > On 29/03/16 09:38, Thomas Goirand wrote:
> >> On 03/23/2016 04:06 PM, Mike Perez wrote:
> >>> Hey all,
> >>>
> >>> I've been talking to a variety of projects about lack of install guides. 
> >>> This
> >>> came from me not having a great experience with trying out projects in 
> >>> the big
> >>> tent.
> >>>
> >>> [...]
> >>
> >> Sorry to jump in this conversation a bit later, as I missed this thread.
> >>
> >> I've contributed lots of entries for Debian, and I'm a bit frustrated to
> >> still not have an active link to it.
> > 
> > I don't understand.  Do you mean that you could have published this 
> > guide yourself, but haven't yet done that;  or that you think someone 
> > else should be publishing it?
> > 
> > Neil
> 
> The documentation people decided to *not* publish the Debian
> install-guide (and remove the link to it) even though it can be
> generated and (to my opinion, which is probably biased) works well.
> 
> I'd like to know the steps needed to restore a working active link.
> 
> I also am not thrived to see that it's been decided to remove completely
> the Debian guide without even asking me about it. First, this isn't
> big-tent-ish spirit (ie: best effort based), and this isn't the first
> time I'm seeing this kind of things happening within the install-guide.
> 
> On each release it's the same: I try to first finish the Debian
> packages, test them well, and *then* work on the install-guide, but when
> this is happening, the Debian install-guide gets removed. I'm not given
> the opportunity to work on it when I have the time to (and my opinion
> isn't even asked).
> 
> I've been told multiple times to get someone else to work on the Debian
> guide. Well, it's not happening, nobody is volunteering, and there's
> only me so far. So what do you propose? Just get rid of my work?

If the core doc team isn't able to help you maintain it, maybe it's a
candidate for a separate guide, just like we're discussing for projects
that aren't part of the DefCore set included in the main guide.

Doug

> 
> Cheers,
> 
> Thomas Goirand (zigo)
> 

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Neil Jerram]

On 29/03/16 12:40, Thomas Goirand wrote:
>
> The documentation people decided to *not* publish the Debian
> install-guide (and remove the link to it) even though it can be
> generated and (to my opinion, which is probably biased) works well.
>
> I'd like to know the steps needed to restore a working active link.
>
> I also am not thrived to see that it's been decided to remove completely
> the Debian guide without even asking me about it. First, this isn't
> big-tent-ish spirit (ie: best effort based), and this isn't the first
> time I'm seeing this kind of things happening within the install-guide.
>
> On each release it's the same: I try to first finish the Debian
> packages, test them well, and *then* work on the install-guide, but when
> this is happening, the Debian install-guide gets removed. I'm not given
> the opportunity to work on it when I have the time to (and my opinion
> isn't even asked).
>
> I've been told multiple times to get someone else to work on the Debian
> guide. Well, it's not happening, nobody is volunteering, and there's
> only me so far. So what do you propose? Just get rid of my work?

Thanks for explaining.  I'd certainly like to see a Debian install guide 
available, if that is achievable.

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] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Thomas Goirand]

On 03/29/2016 11:56 AM, Neil Jerram wrote:
> On 29/03/16 09:38, Thomas Goirand wrote:
>> On 03/23/2016 04:06 PM, Mike Perez wrote:
>>> Hey all,
>>>
>>> I've been talking to a variety of projects about lack of install guides. 
>>> This
>>> came from me not having a great experience with trying out projects in the 
>>> big
>>> tent.
>>>
>>> [...]
>>
>> Sorry to jump in this conversation a bit later, as I missed this thread.
>>
>> I've contributed lots of entries for Debian, and I'm a bit frustrated to
>> still not have an active link to it.
> 
> I don't understand.  Do you mean that you could have published this 
> guide yourself, but haven't yet done that;  or that you think someone 
> else should be publishing it?
> 
>   Neil

The documentation people decided to *not* publish the Debian
install-guide (and remove the link to it) even though it can be
generated and (to my opinion, which is probably biased) works well.

I'd like to know the steps needed to restore a working active link.

I also am not thrived to see that it's been decided to remove completely
the Debian guide without even asking me about it. First, this isn't
big-tent-ish spirit (ie: best effort based), and this isn't the first
time I'm seeing this kind of things happening within the install-guide.

On each release it's the same: I try to first finish the Debian
packages, test them well, and *then* work on the install-guide, but when
this is happening, the Debian install-guide gets removed. I'm not given
the opportunity to work on it when I have the time to (and my opinion
isn't even asked).

I've been told multiple times to get someone else to work on the Debian
guide. Well, it's not happening, nobody is volunteering, and there's
only me so far. So what do you propose? Just get rid of my work?

Cheers,

Thomas Goirand (zigo)


__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Neil Jerram]

On 29/03/16 09:38, Thomas Goirand wrote:
> On 03/23/2016 04:06 PM, Mike Perez wrote:
>> Hey all,
>>
>> I've been talking to a variety of projects about lack of install guides. This
>> came from me not having a great experience with trying out projects in the 
>> big
>> tent.
>>
>> [...]
>
> Sorry to jump in this conversation a bit later, as I missed this thread.
>
> I've contributed lots of entries for Debian, and I'm a bit frustrated to
> still not have an active link to it.

I don't understand.  Do you mean that you could have published this 
guide yourself, but haven't yet done that;  or that you think someone 
else should be publishing it?

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] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Thomas Goirand]

On 03/23/2016 04:06 PM, Mike Perez wrote:
> Hey all,
> 
> I've been talking to a variety of projects about lack of install guides. This
> came from me not having a great experience with trying out projects in the big
> tent.
> 
> [...]

Sorry to jump in this conversation a bit later, as I missed this thread.

I've contributed lots of entries for Debian, and I'm a bit frustrated to
still not have an active link to it.

The reason is that nobody (beside me) ran a full manual test of the
Debian install-guide. As I'm in a direct conflict of interest, I prefer
someone else does it, but it's not happening.

So, I'm a bit loss into what should be done to unlock this situation.
I'd like to have directions, and if possible, someone to help with the
Debian guide, at least for testing what has been done.

Thoughts anyone?

Cheers,

Thomas Goirand (zigo)


__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Ronald Bradford]

The only downside I see of these examples are there is no way in the
documentation to determine the release version or cycle.  (i.e. you have to
read the contents in conjunction with the URL).

Ronald Bradford

Web Site: http://ronaldbradford.com
LinkedIn:  http://www.linkedin.com/in/ronaldbradford
Twitter:@RonaldBradford 
Skype: RonaldBradford
GTalk: Ronald.Bradford
IRC: rbradfor


On Fri, Mar 25, 2016 at 4:20 PM, Jim Rollenhagen 
wrote:

> On Fri, Mar 25, 2016 at 03:20:30PM -0400, Doug Hellmann wrote:
> > Excerpts from Jim Rollenhagen's message of 2016-03-25 10:45:30 -0700:
> > > On Fri, Mar 25, 2016 at 09:10:05AM -0400, Doug Hellmann wrote:
> > > > Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000:
> > > > > On 24/03/16 08:01, Doug Hellmann wrote:
> > > > > > Excerpts from Lana Brindley's message of 2016-03-24 07:14:35
> +1000:
> > > > > >> Hi Mike, and sorry I missed you on IRC to discuss this there.
> That said, I think it's great that you took this to the mailing list,
> especially seeing the conversation that has ensued.
> > > > > >>
> > > > > >> More inline ...
> > > > > >>
> > > > > >> On 24/03/16 01:06, Mike Perez wrote:
> > > > > >>> Hey all,
> > > > > >>>
> > > > > >>> I've been talking to a variety of projects about lack of
> install guides. This
> > > > > >>> came from me not having a great experience with trying out
> projects in the big
> > > > > >>> tent.
> > > > > >>>
> > > > > >>> Projects like Manila have proposed install docs [1], but they
> were rejected
> > > > > >>> by the install docs team because it's not in defcore. One of
> Manila's goals of
> > > > > >>> getting these docs accepted is to apply for the operators tag
> > > > > >>> ops:docs:install-guide [2] so that it helps their maturity
> level in the project
> > > > > >>> navigator [3].
> > > > > >>>
> > > > > >>> Adrian Otto expressed to me having the same issue for Magnum.
> I think it's
> > > > > >>> funny that a project that gets keynote time at the OpenStack
> conference can't
> > > > > >>> be in the install docs personally.
> > > > > >>>
> > > > > >>> As seen from the Manila review [1], the install docs team is
> suggesting these
> > > > > >>> to be put in their developer guide.
> > > > > >>
> > > > > >> As Steve pointed out, these now have solid plans to go in. That
> was because both projects opened a conversation with us and we worked with
> them over time to give them the docs they required.
> > > > > >>
> > > > > >>>
> > > > > >>> I don't think this is a great idea. Mainly because they are
> for developers,
> > > > > >>> operators aren't going to be looking in there for install
> information. Also the
> > > > > >>> Developer doc page [4] even states "This page contains
> documentation for Python
> > > > > >>> developers, who work on OpenStack itself".
> > > > > >>
> > > > > >> I agree, but it's a great place to start. In fact, I've just
> merged a change to the Docs Contributor Guide (on the back of a previous
> mailing list conversation) that explicitly states this:
> > > > > >>
> > > > > >>
> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> > > > > >
> > > > > > I think you're missing that most of us are disagreeing that it is
> > > > > > a good place to start. It's fine to have the docs in a repository
> > > > > > managed by the project team. It's not good at all to publish them
> > > > > > under docs.o.o/developer because they are not for developers, and
> > > > > > so it's confusing. This is why we ended up with a different place
> > > > > > for release notes to be published, instead of just adding reno to
> > > > > > the existing developer documentation build, for example.
> > > > > >
> > > > >
> > > > > All docs need to be drafted somewhere. I don't care where that is,
> but make the suggestion of /developer because at least it's accessible
> there, and also because it's managed in the project's own repo. If you want
> to create a different place, or rename /developer to be more inclusive, I
> think that's a great idea.
> > > >
> > > > I think we'll want to add a new location, or publish to a similar
> > > > location to the existing install guide. I found, for example
> > > > http://docs.openstack.org/mitaka/install-guide-ubuntu/
> > > >
> > > > If we take ironic as the example, and assume all OS-types would be
> > > > covered in one manual, we could make that:
> > > >
> > > > (1) http://docs.openstack.org/mitaka/ironic/install-guide/
> > > > (2) http://docs.openstack.org/ironic/mitaka/install-guide/
> > > > (3) http://docs.openstack.org/install-guide/ironic/
> > > > (4) http://docs.openstack.org/ironic/install-guide/
> > > >
> > > > I like options 3 and 4. To keep things simple for the project teams,
> > > > I think we want to skip including the release series in the base
> > > > URL.  As the instructions change, projects may need to create
> > > > separate sub-sections of their guide 

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Jim Rollenhagen]

On Fri, Mar 25, 2016 at 03:20:30PM -0400, Doug Hellmann wrote:
> Excerpts from Jim Rollenhagen's message of 2016-03-25 10:45:30 -0700:
> > On Fri, Mar 25, 2016 at 09:10:05AM -0400, Doug Hellmann wrote:
> > > Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000:
> > > > On 24/03/16 08:01, Doug Hellmann wrote:
> > > > > Excerpts from Lana Brindley's message of 2016-03-24 07:14:35 +1000:
> > > > >> Hi Mike, and sorry I missed you on IRC to discuss this there. That 
> > > > >> said, I think it's great that you took this to the mailing list, 
> > > > >> especially seeing the conversation that has ensued.
> > > > >>
> > > > >> More inline ...
> > > > >>
> > > > >> On 24/03/16 01:06, Mike Perez wrote:
> > > > >>> Hey all,
> > > > >>>
> > > > >>> I've been talking to a variety of projects about lack of install 
> > > > >>> guides. This
> > > > >>> came from me not having a great experience with trying out projects 
> > > > >>> in the big
> > > > >>> tent.
> > > > >>>
> > > > >>> Projects like Manila have proposed install docs [1], but they were 
> > > > >>> rejected
> > > > >>> by the install docs team because it's not in defcore. One of 
> > > > >>> Manila's goals of
> > > > >>> getting these docs accepted is to apply for the operators tag
> > > > >>> ops:docs:install-guide [2] so that it helps their maturity level in 
> > > > >>> the project
> > > > >>> navigator [3].
> > > > >>>
> > > > >>> Adrian Otto expressed to me having the same issue for Magnum. I 
> > > > >>> think it's
> > > > >>> funny that a project that gets keynote time at the OpenStack 
> > > > >>> conference can't
> > > > >>> be in the install docs personally.
> > > > >>>
> > > > >>> As seen from the Manila review [1], the install docs team is 
> > > > >>> suggesting these
> > > > >>> to be put in their developer guide.
> > > > >>
> > > > >> As Steve pointed out, these now have solid plans to go in. That was 
> > > > >> because both projects opened a conversation with us and we worked 
> > > > >> with them over time to give them the docs they required.
> > > > >>
> > > > >>>
> > > > >>> I don't think this is a great idea. Mainly because they are for 
> > > > >>> developers,
> > > > >>> operators aren't going to be looking in there for install 
> > > > >>> information. Also the
> > > > >>> Developer doc page [4] even states "This page contains 
> > > > >>> documentation for Python
> > > > >>> developers, who work on OpenStack itself".
> > > > >>
> > > > >> I agree, but it's a great place to start. In fact, I've just merged 
> > > > >> a change to the Docs Contributor Guide (on the back of a previous 
> > > > >> mailing list conversation) that explicitly states this:
> > > > >>
> > > > >> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> > > > > 
> > > > > I think you're missing that most of us are disagreeing that it is
> > > > > a good place to start. It's fine to have the docs in a repository
> > > > > managed by the project team. It's not good at all to publish them
> > > > > under docs.o.o/developer because they are not for developers, and
> > > > > so it's confusing. This is why we ended up with a different place
> > > > > for release notes to be published, instead of just adding reno to
> > > > > the existing developer documentation build, for example.
> > > > > 
> > > > 
> > > > All docs need to be drafted somewhere. I don't care where that is, but 
> > > > make the suggestion of /developer because at least it's accessible 
> > > > there, and also because it's managed in the project's own repo. If you 
> > > > want to create a different place, or rename /developer to be more 
> > > > inclusive, I think that's a great idea.
> > > 
> > > I think we'll want to add a new location, or publish to a similar
> > > location to the existing install guide. I found, for example
> > > http://docs.openstack.org/mitaka/install-guide-ubuntu/
> > > 
> > > If we take ironic as the example, and assume all OS-types would be
> > > covered in one manual, we could make that:
> > > 
> > > (1) http://docs.openstack.org/mitaka/ironic/install-guide/
> > > (2) http://docs.openstack.org/ironic/mitaka/install-guide/
> > > (3) http://docs.openstack.org/install-guide/ironic/
> > > (4) http://docs.openstack.org/ironic/install-guide/
> > > 
> > > I like options 3 and 4. To keep things simple for the project teams,
> > > I think we want to skip including the release series in the base
> > > URL.  As the instructions change, projects may need to create
> > > separate sub-sections of their guide for each series, but they
> > > should be able to do that without having to set up separate publishing
> > > locations and jobs.
> > > 
> > > Another benefit of options 3 and 4 is that as the ironic team
> > > produces other guides, those can go under a consistent URL that
> > > makes it relatively simple to set up a generic publishing job for
> > > all projects. Option 4 does have the benefit of making it easy to
> > > have a page at 

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Doug Hellmann]

Excerpts from Andreas Jaeger's message of 2016-03-25 20:30:01 +0100:
> On 03/25/2016 08:20 PM, Doug Hellmann wrote:
> > Excerpts from Jim Rollenhagen's message of 2016-03-25 10:45:30 -0700:
> >> > On Fri, Mar 25, 2016 at 09:10:05AM -0400, Doug Hellmann wrote:
> >>> > > Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000:
>  > > > On 24/03/16 08:01, Doug Hellmann wrote:
> > > > > > Excerpts from Lana Brindley's message of 2016-03-24 07:14:35 
> > > > > > +1000:
> >> > > > >> Hi Mike, and sorry I missed you on IRC to discuss this there. 
> >> > > > >> That said, I think it's great that you took this to the 
> >> > > > >> mailing list, especially seeing the conversation that has 
> >> > > > >> ensued.
> >> > > > >>
> >> > > > >> More inline ...
> >> > > > >>
> >> > > > >> On 24/03/16 01:06, Mike Perez wrote:
> >>> > > > >>> Hey all,
> >>> > > > >>>
> >>> > > > >>> I've been talking to a variety of projects about lack of 
> >>> > > > >>> install guides. This
> >>> > > > >>> came from me not having a great experience with trying out 
> >>> > > > >>> projects in the big
> >>> > > > >>> tent.
> >>> > > > >>>
> >>> > > > >>> Projects like Manila have proposed install docs [1], but 
> >>> > > > >>> they were rejected
> >>> > > > >>> by the install docs team because it's not in defcore. One 
> >>> > > > >>> of Manila's goals of
> >>> > > > >>> getting these docs accepted is to apply for the operators 
> >>> > > > >>> tag
> >>> > > > >>> ops:docs:install-guide [2] so that it helps their maturity 
> >>> > > > >>> level in the project
> >>> > > > >>> navigator [3].
> >>> > > > >>>
> >>> > > > >>> Adrian Otto expressed to me having the same issue for 
> >>> > > > >>> Magnum. I think it's
> >>> > > > >>> funny that a project that gets keynote time at the 
> >>> > > > >>> OpenStack conference can't
> >>> > > > >>> be in the install docs personally.
> >>> > > > >>>
> >>> > > > >>> As seen from the Manila review [1], the install docs team 
> >>> > > > >>> is suggesting these
> >>> > > > >>> to be put in their developer guide.
> >> > > > >>
> >> > > > >> As Steve pointed out, these now have solid plans to go in. 
> >> > > > >> That was because both projects opened a conversation with us 
> >> > > > >> and we worked with them over time to give them the docs they 
> >> > > > >> required.
> >> > > > >>
> >>> > > > >>>
> >>> > > > >>> I don't think this is a great idea. Mainly because they are 
> >>> > > > >>> for developers,
> >>> > > > >>> operators aren't going to be looking in there for install 
> >>> > > > >>> information. Also the
> >>> > > > >>> Developer doc page [4] even states "This page contains 
> >>> > > > >>> documentation for Python
> >>> > > > >>> developers, who work on OpenStack itself".
> >> > > > >>
> >> > > > >> I agree, but it's a great place to start. In fact, I've just 
> >> > > > >> merged a change to the Docs Contributor Guide (on the back of 
> >> > > > >> a previous mailing list conversation) that explicitly states 
> >> > > > >> this:
> >> > > > >>
> >> > > > >> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> > > > > > 
> > > > > > I think you're missing that most of us are disagreeing that it 
> > > > > > is
> > > > > > a good place to start. It's fine to have the docs in a 
> > > > > > repository
> > > > > > managed by the project team. It's not good at all to publish 
> > > > > > them
> > > > > > under docs.o.o/developer because they are not for developers, 
> > > > > > and
> > > > > > so it's confusing. This is why we ended up with a different 
> > > > > > place
> > > > > > for release notes to be published, instead of just adding reno 
> > > > > > to
> > > > > > the existing developer documentation build, for example.
> > > > > > 
>  > > > 
>  > > > All docs need to be drafted somewhere. I don't care where that is, 
>  > > > but make the suggestion of /developer because at least it's 
>  > > > accessible there, and also because it's managed in the project's 
>  > > > own repo. If you want to create a different place, or rename 
>  > > > /developer to be more inclusive, I think that's a great idea.
> >>> > > 
> >>> > > I think we'll want to add a new location, or publish to a similar
> >>> > > location to the existing install guide. I found, for example
> >>> > > http://docs.openstack.org/mitaka/install-guide-ubuntu/
> >>> > > 
> >>> > > If we take ironic as the example, and assume all OS-types would be
> >>> > > covered in one manual, we could make that:
> >>> > > 
> >>> > > (1) http://docs.openstack.org/mitaka/ironic/install-guide/
> >>> > > (2) http://docs.openstack.org/ironic/mitaka/install-guide/
> >>> > > (3) 

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Andreas Jaeger]

On 03/25/2016 08:20 PM, Doug Hellmann wrote:
> Excerpts from Jim Rollenhagen's message of 2016-03-25 10:45:30 -0700:
>> > On Fri, Mar 25, 2016 at 09:10:05AM -0400, Doug Hellmann wrote:
>>> > > Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000:
 > > > On 24/03/16 08:01, Doug Hellmann wrote:
> > > > > Excerpts from Lana Brindley's message of 2016-03-24 07:14:35 
> > > > > +1000:
>> > > > >> Hi Mike, and sorry I missed you on IRC to discuss this there. 
>> > > > >> That said, I think it's great that you took this to the mailing 
>> > > > >> list, especially seeing the conversation that has ensued.
>> > > > >>
>> > > > >> More inline ...
>> > > > >>
>> > > > >> On 24/03/16 01:06, Mike Perez wrote:
>>> > > > >>> Hey all,
>>> > > > >>>
>>> > > > >>> I've been talking to a variety of projects about lack of 
>>> > > > >>> install guides. This
>>> > > > >>> came from me not having a great experience with trying out 
>>> > > > >>> projects in the big
>>> > > > >>> tent.
>>> > > > >>>
>>> > > > >>> Projects like Manila have proposed install docs [1], but they 
>>> > > > >>> were rejected
>>> > > > >>> by the install docs team because it's not in defcore. One of 
>>> > > > >>> Manila's goals of
>>> > > > >>> getting these docs accepted is to apply for the operators tag
>>> > > > >>> ops:docs:install-guide [2] so that it helps their maturity 
>>> > > > >>> level in the project
>>> > > > >>> navigator [3].
>>> > > > >>>
>>> > > > >>> Adrian Otto expressed to me having the same issue for Magnum. 
>>> > > > >>> I think it's
>>> > > > >>> funny that a project that gets keynote time at the OpenStack 
>>> > > > >>> conference can't
>>> > > > >>> be in the install docs personally.
>>> > > > >>>
>>> > > > >>> As seen from the Manila review [1], the install docs team is 
>>> > > > >>> suggesting these
>>> > > > >>> to be put in their developer guide.
>> > > > >>
>> > > > >> As Steve pointed out, these now have solid plans to go in. That 
>> > > > >> was because both projects opened a conversation with us and we 
>> > > > >> worked with them over time to give them the docs they required.
>> > > > >>
>>> > > > >>>
>>> > > > >>> I don't think this is a great idea. Mainly because they are 
>>> > > > >>> for developers,
>>> > > > >>> operators aren't going to be looking in there for install 
>>> > > > >>> information. Also the
>>> > > > >>> Developer doc page [4] even states "This page contains 
>>> > > > >>> documentation for Python
>>> > > > >>> developers, who work on OpenStack itself".
>> > > > >>
>> > > > >> I agree, but it's a great place to start. In fact, I've just 
>> > > > >> merged a change to the Docs Contributor Guide (on the back of a 
>> > > > >> previous mailing list conversation) that explicitly states this:
>> > > > >>
>> > > > >> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> > > > > 
> > > > > I think you're missing that most of us are disagreeing that it is
> > > > > a good place to start. It's fine to have the docs in a repository
> > > > > managed by the project team. It's not good at all to publish them
> > > > > under docs.o.o/developer because they are not for developers, and
> > > > > so it's confusing. This is why we ended up with a different place
> > > > > for release notes to be published, instead of just adding reno to
> > > > > the existing developer documentation build, for example.
> > > > > 
 > > > 
 > > > All docs need to be drafted somewhere. I don't care where that is, 
 > > > but make the suggestion of /developer because at least it's 
 > > > accessible there, and also because it's managed in the project's own 
 > > > repo. If you want to create a different place, or rename /developer 
 > > > to be more inclusive, I think that's a great idea.
>>> > > 
>>> > > I think we'll want to add a new location, or publish to a similar
>>> > > location to the existing install guide. I found, for example
>>> > > http://docs.openstack.org/mitaka/install-guide-ubuntu/
>>> > > 
>>> > > If we take ironic as the example, and assume all OS-types would be
>>> > > covered in one manual, we could make that:
>>> > > 
>>> > > (1) http://docs.openstack.org/mitaka/ironic/install-guide/
>>> > > (2) http://docs.openstack.org/ironic/mitaka/install-guide/
>>> > > (3) http://docs.openstack.org/install-guide/ironic/
>>> > > (4) http://docs.openstack.org/ironic/install-guide/
>>> > > 
>>> > > I like options 3 and 4. To keep things simple for the project teams,
>>> > > I think we want to skip including the release series in the base
>>> > > URL.  As the instructions change, projects may need to create
>>> > > separate sub-sections of their guide for each series, but they
>>> > > should be able to do that 

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Doug Hellmann]

Excerpts from Jim Rollenhagen's message of 2016-03-25 10:45:30 -0700:
> On Fri, Mar 25, 2016 at 09:10:05AM -0400, Doug Hellmann wrote:
> > Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000:
> > > On 24/03/16 08:01, Doug Hellmann wrote:
> > > > Excerpts from Lana Brindley's message of 2016-03-24 07:14:35 +1000:
> > > >> Hi Mike, and sorry I missed you on IRC to discuss this there. That 
> > > >> said, I think it's great that you took this to the mailing list, 
> > > >> especially seeing the conversation that has ensued.
> > > >>
> > > >> More inline ...
> > > >>
> > > >> On 24/03/16 01:06, Mike Perez wrote:
> > > >>> Hey all,
> > > >>>
> > > >>> I've been talking to a variety of projects about lack of install 
> > > >>> guides. This
> > > >>> came from me not having a great experience with trying out projects 
> > > >>> in the big
> > > >>> tent.
> > > >>>
> > > >>> Projects like Manila have proposed install docs [1], but they were 
> > > >>> rejected
> > > >>> by the install docs team because it's not in defcore. One of Manila's 
> > > >>> goals of
> > > >>> getting these docs accepted is to apply for the operators tag
> > > >>> ops:docs:install-guide [2] so that it helps their maturity level in 
> > > >>> the project
> > > >>> navigator [3].
> > > >>>
> > > >>> Adrian Otto expressed to me having the same issue for Magnum. I think 
> > > >>> it's
> > > >>> funny that a project that gets keynote time at the OpenStack 
> > > >>> conference can't
> > > >>> be in the install docs personally.
> > > >>>
> > > >>> As seen from the Manila review [1], the install docs team is 
> > > >>> suggesting these
> > > >>> to be put in their developer guide.
> > > >>
> > > >> As Steve pointed out, these now have solid plans to go in. That was 
> > > >> because both projects opened a conversation with us and we worked with 
> > > >> them over time to give them the docs they required.
> > > >>
> > > >>>
> > > >>> I don't think this is a great idea. Mainly because they are for 
> > > >>> developers,
> > > >>> operators aren't going to be looking in there for install 
> > > >>> information. Also the
> > > >>> Developer doc page [4] even states "This page contains documentation 
> > > >>> for Python
> > > >>> developers, who work on OpenStack itself".
> > > >>
> > > >> I agree, but it's a great place to start. In fact, I've just merged a 
> > > >> change to the Docs Contributor Guide (on the back of a previous 
> > > >> mailing list conversation) that explicitly states this:
> > > >>
> > > >> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> > > > 
> > > > I think you're missing that most of us are disagreeing that it is
> > > > a good place to start. It's fine to have the docs in a repository
> > > > managed by the project team. It's not good at all to publish them
> > > > under docs.o.o/developer because they are not for developers, and
> > > > so it's confusing. This is why we ended up with a different place
> > > > for release notes to be published, instead of just adding reno to
> > > > the existing developer documentation build, for example.
> > > > 
> > > 
> > > All docs need to be drafted somewhere. I don't care where that is, but 
> > > make the suggestion of /developer because at least it's accessible there, 
> > > and also because it's managed in the project's own repo. If you want to 
> > > create a different place, or rename /developer to be more inclusive, I 
> > > think that's a great idea.
> > 
> > I think we'll want to add a new location, or publish to a similar
> > location to the existing install guide. I found, for example
> > http://docs.openstack.org/mitaka/install-guide-ubuntu/
> > 
> > If we take ironic as the example, and assume all OS-types would be
> > covered in one manual, we could make that:
> > 
> > (1) http://docs.openstack.org/mitaka/ironic/install-guide/
> > (2) http://docs.openstack.org/ironic/mitaka/install-guide/
> > (3) http://docs.openstack.org/install-guide/ironic/
> > (4) http://docs.openstack.org/ironic/install-guide/
> > 
> > I like options 3 and 4. To keep things simple for the project teams,
> > I think we want to skip including the release series in the base
> > URL.  As the instructions change, projects may need to create
> > separate sub-sections of their guide for each series, but they
> > should be able to do that without having to set up separate publishing
> > locations and jobs.
> > 
> > Another benefit of options 3 and 4 is that as the ironic team
> > produces other guides, those can go under a consistent URL that
> > makes it relatively simple to set up a generic publishing job for
> > all projects. Option 4 does have the benefit of making it easy to
> > have a page at http://docs.openstack.org/ironic/ linking to all of
> > the guides the ironic team has published.
> > 
> > Thoughts?
> 
> I also like 3 and 4. I like 3 because it's a similar structure to the
> developer docs, however I do like 4 giving us the option to publish
> other 

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Doug Hellmann]

Excerpts from Mike Perez's message of 2016-03-25 11:32:58 -0700:
> > On Mar 25, 2016, at 06:10, Doug Hellmann  wrote:
> > 
> > Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000:
> >> 
> >> All docs need to be drafted somewhere. I don't care where that is, but 
> >> make the suggestion of /developer because at least it's accessible there, 
> >> and also because it's managed in the project's own repo. If you want to 
> >> create a different place, or rename /developer to be more inclusive, I 
> >> think that's a great idea.
> > 
> > I think we'll want to add a new location, or publish to a similar
> > location to the existing install guide. I found, for example
> > http://docs.openstack.org/mitaka/install-guide-ubuntu/
> > 
> > If we take ironic as the example, and assume all OS-types would be
> > covered in one manual, we could make that:
> > 
> > (1) http://docs.openstack.org/mitaka/ironic/install-guide/
> > (2) http://docs.openstack.org/ironic/mitaka/install-guide/
> > (3) http://docs.openstack.org/install-guide/ironic/
> > (4) http://docs.openstack.org/ironic/install-guide/
> 
> I like option 3.
> 
> All install guides would be discoverable at /install-guides that are rendered 
> docs from individual projects' repos.
> 
> Regardless of what direction people would like to go here, I will be happy to 
> spearhead this from a cross-project perspective.

Thanks, Mike, that would be good. I'm happy to help out, too.

Doug

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Jim Rollenhagen]

On Fri, Mar 25, 2016 at 11:32:58AM -0700, Mike Perez wrote:
> > On Mar 25, 2016, at 06:10, Doug Hellmann  wrote:
> > 
> > Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000:
> >> 
> >> All docs need to be drafted somewhere. I don't care where that is, but 
> >> make the suggestion of /developer because at least it's accessible there, 
> >> and also because it's managed in the project's own repo. If you want to 
> >> create a different place, or rename /developer to be more inclusive, I 
> >> think that's a great idea.
> > 
> > I think we'll want to add a new location, or publish to a similar
> > location to the existing install guide. I found, for example
> > http://docs.openstack.org/mitaka/install-guide-ubuntu/
> > 
> > If we take ironic as the example, and assume all OS-types would be
> > covered in one manual, we could make that:
> > 
> > (1) http://docs.openstack.org/mitaka/ironic/install-guide/
> > (2) http://docs.openstack.org/ironic/mitaka/install-guide/
> > (3) http://docs.openstack.org/install-guide/ironic/
> > (4) http://docs.openstack.org/ironic/install-guide/
> 
> I like option 3.
> 
> All install guides would be discoverable at /install-guides that are rendered 
> docs from individual projects' repos.

Yeah, that's a good point. I like it. Probably with a dropdown or
something to choose a specific version.

// jim

> 
> Regardless of what direction people would like to go here, I will be happy to 
> spearhead this from a cross-project perspective.
> 
> --
> Mike Perez
> __
> 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] Our Install Guides Only Cover Defcore - What about big tent?

[Mike Perez]

> On Mar 25, 2016, at 06:10, Doug Hellmann  wrote:
> 
> Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000:
>> 
>> All docs need to be drafted somewhere. I don't care where that is, but make 
>> the suggestion of /developer because at least it's accessible there, and 
>> also because it's managed in the project's own repo. If you want to create a 
>> different place, or rename /developer to be more inclusive, I think that's a 
>> great idea.
> 
> I think we'll want to add a new location, or publish to a similar
> location to the existing install guide. I found, for example
> http://docs.openstack.org/mitaka/install-guide-ubuntu/
> 
> If we take ironic as the example, and assume all OS-types would be
> covered in one manual, we could make that:
> 
> (1) http://docs.openstack.org/mitaka/ironic/install-guide/
> (2) http://docs.openstack.org/ironic/mitaka/install-guide/
> (3) http://docs.openstack.org/install-guide/ironic/
> (4) http://docs.openstack.org/ironic/install-guide/

I like option 3.

All install guides would be discoverable at /install-guides that are rendered 
docs from individual projects' repos.

Regardless of what direction people would like to go here, I will be happy to 
spearhead this from a cross-project perspective.

--
Mike Perez
__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Jim Rollenhagen]

On Fri, Mar 25, 2016 at 09:10:05AM -0400, Doug Hellmann wrote:
> Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000:
> > On 24/03/16 08:01, Doug Hellmann wrote:
> > > Excerpts from Lana Brindley's message of 2016-03-24 07:14:35 +1000:
> > >> Hi Mike, and sorry I missed you on IRC to discuss this there. That said, 
> > >> I think it's great that you took this to the mailing list, especially 
> > >> seeing the conversation that has ensued.
> > >>
> > >> More inline ...
> > >>
> > >> On 24/03/16 01:06, Mike Perez wrote:
> > >>> Hey all,
> > >>>
> > >>> I've been talking to a variety of projects about lack of install 
> > >>> guides. This
> > >>> came from me not having a great experience with trying out projects in 
> > >>> the big
> > >>> tent.
> > >>>
> > >>> Projects like Manila have proposed install docs [1], but they were 
> > >>> rejected
> > >>> by the install docs team because it's not in defcore. One of Manila's 
> > >>> goals of
> > >>> getting these docs accepted is to apply for the operators tag
> > >>> ops:docs:install-guide [2] so that it helps their maturity level in the 
> > >>> project
> > >>> navigator [3].
> > >>>
> > >>> Adrian Otto expressed to me having the same issue for Magnum. I think 
> > >>> it's
> > >>> funny that a project that gets keynote time at the OpenStack conference 
> > >>> can't
> > >>> be in the install docs personally.
> > >>>
> > >>> As seen from the Manila review [1], the install docs team is suggesting 
> > >>> these
> > >>> to be put in their developer guide.
> > >>
> > >> As Steve pointed out, these now have solid plans to go in. That was 
> > >> because both projects opened a conversation with us and we worked with 
> > >> them over time to give them the docs they required.
> > >>
> > >>>
> > >>> I don't think this is a great idea. Mainly because they are for 
> > >>> developers,
> > >>> operators aren't going to be looking in there for install information. 
> > >>> Also the
> > >>> Developer doc page [4] even states "This page contains documentation 
> > >>> for Python
> > >>> developers, who work on OpenStack itself".
> > >>
> > >> I agree, but it's a great place to start. In fact, I've just merged a 
> > >> change to the Docs Contributor Guide (on the back of a previous mailing 
> > >> list conversation) that explicitly states this:
> > >>
> > >> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> > > 
> > > I think you're missing that most of us are disagreeing that it is
> > > a good place to start. It's fine to have the docs in a repository
> > > managed by the project team. It's not good at all to publish them
> > > under docs.o.o/developer because they are not for developers, and
> > > so it's confusing. This is why we ended up with a different place
> > > for release notes to be published, instead of just adding reno to
> > > the existing developer documentation build, for example.
> > > 
> > 
> > All docs need to be drafted somewhere. I don't care where that is, but make 
> > the suggestion of /developer because at least it's accessible there, and 
> > also because it's managed in the project's own repo. If you want to create 
> > a different place, or rename /developer to be more inclusive, I think 
> > that's a great idea.
> 
> I think we'll want to add a new location, or publish to a similar
> location to the existing install guide. I found, for example
> http://docs.openstack.org/mitaka/install-guide-ubuntu/
> 
> If we take ironic as the example, and assume all OS-types would be
> covered in one manual, we could make that:
> 
> (1) http://docs.openstack.org/mitaka/ironic/install-guide/
> (2) http://docs.openstack.org/ironic/mitaka/install-guide/
> (3) http://docs.openstack.org/install-guide/ironic/
> (4) http://docs.openstack.org/ironic/install-guide/
> 
> I like options 3 and 4. To keep things simple for the project teams,
> I think we want to skip including the release series in the base
> URL.  As the instructions change, projects may need to create
> separate sub-sections of their guide for each series, but they
> should be able to do that without having to set up separate publishing
> locations and jobs.
> 
> Another benefit of options 3 and 4 is that as the ironic team
> produces other guides, those can go under a consistent URL that
> makes it relatively simple to set up a generic publishing job for
> all projects. Option 4 does have the benefit of making it easy to
> have a page at http://docs.openstack.org/ironic/ linking to all of
> the guides the ironic team has published.
> 
> Thoughts?

I also like 3 and 4. I like 3 because it's a similar structure to the
developer docs, however I do like 4 giving us the option to publish
other guides (and perhaps we could move the developer docs to
/ironic/developer).

I do think we should be able to publish per-release versions of the
install guide (or any other guides) similar to how we publish developer
docs per-release today. For example:

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Doug Hellmann]

Excerpts from Lana Brindley's message of 2016-03-24 08:50:49 +1000:
> On 24/03/16 08:01, Doug Hellmann wrote:
> > Excerpts from Lana Brindley's message of 2016-03-24 07:14:35 +1000:
> >> Hi Mike, and sorry I missed you on IRC to discuss this there. That said, I 
> >> think it's great that you took this to the mailing list, especially seeing 
> >> the conversation that has ensued.
> >>
> >> More inline ...
> >>
> >> On 24/03/16 01:06, Mike Perez wrote:
> >>> Hey all,
> >>>
> >>> I've been talking to a variety of projects about lack of install guides. 
> >>> This
> >>> came from me not having a great experience with trying out projects in 
> >>> the big
> >>> tent.
> >>>
> >>> Projects like Manila have proposed install docs [1], but they were 
> >>> rejected
> >>> by the install docs team because it's not in defcore. One of Manila's 
> >>> goals of
> >>> getting these docs accepted is to apply for the operators tag
> >>> ops:docs:install-guide [2] so that it helps their maturity level in the 
> >>> project
> >>> navigator [3].
> >>>
> >>> Adrian Otto expressed to me having the same issue for Magnum. I think it's
> >>> funny that a project that gets keynote time at the OpenStack conference 
> >>> can't
> >>> be in the install docs personally.
> >>>
> >>> As seen from the Manila review [1], the install docs team is suggesting 
> >>> these
> >>> to be put in their developer guide.
> >>
> >> As Steve pointed out, these now have solid plans to go in. That was 
> >> because both projects opened a conversation with us and we worked with 
> >> them over time to give them the docs they required.
> >>
> >>>
> >>> I don't think this is a great idea. Mainly because they are for 
> >>> developers,
> >>> operators aren't going to be looking in there for install information. 
> >>> Also the
> >>> Developer doc page [4] even states "This page contains documentation for 
> >>> Python
> >>> developers, who work on OpenStack itself".
> >>
> >> I agree, but it's a great place to start. In fact, I've just merged a 
> >> change to the Docs Contributor Guide (on the back of a previous mailing 
> >> list conversation) that explicitly states this:
> >>
> >> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> > 
> > I think you're missing that most of us are disagreeing that it is
> > a good place to start. It's fine to have the docs in a repository
> > managed by the project team. It's not good at all to publish them
> > under docs.o.o/developer because they are not for developers, and
> > so it's confusing. This is why we ended up with a different place
> > for release notes to be published, instead of just adding reno to
> > the existing developer documentation build, for example.
> > 
> 
> All docs need to be drafted somewhere. I don't care where that is, but make 
> the suggestion of /developer because at least it's accessible there, and also 
> because it's managed in the project's own repo. If you want to create a 
> different place, or rename /developer to be more inclusive, I think that's a 
> great idea.

I think we'll want to add a new location, or publish to a similar
location to the existing install guide. I found, for example
http://docs.openstack.org/mitaka/install-guide-ubuntu/

If we take ironic as the example, and assume all OS-types would be
covered in one manual, we could make that:

(1) http://docs.openstack.org/mitaka/ironic/install-guide/
(2) http://docs.openstack.org/ironic/mitaka/install-guide/
(3) http://docs.openstack.org/install-guide/ironic/
(4) http://docs.openstack.org/ironic/install-guide/

I like options 3 and 4. To keep things simple for the project teams,
I think we want to skip including the release series in the base
URL.  As the instructions change, projects may need to create
separate sub-sections of their guide for each series, but they
should be able to do that without having to set up separate publishing
locations and jobs.

Another benefit of options 3 and 4 is that as the ironic team
produces other guides, those can go under a consistent URL that
makes it relatively simple to set up a generic publishing job for
all projects. Option 4 does have the benefit of making it easy to
have a page at http://docs.openstack.org/ironic/ linking to all of
the guides the ironic team has published.

Thoughts?

> > Right. The solution to that isn't to say "we aren't going to document
> > it at all" or "publish the documentation somewhere less ideal",
> > though, which is what it sounds like we're doing now.  It's to say
> 
> Actually, I said that I acknowledge that isn't working, and we need to find a 
> different solution.

OK, that wasn't clear to me from your message that continued to suggest
publishing to a location under /developer.

Doug

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Jim Rollenhagen]

On Wed, Mar 23, 2016 at 06:02:47PM -0400, Doug Hellmann wrote:
> Excerpts from Jim Rollenhagen's message of 2016-03-23 14:46:16 -0700:
> > On Thu, Mar 24, 2016 at 07:14:35AM +1000, Lana Brindley wrote:
> > > -BEGIN PGP SIGNED MESSAGE-
> > > Hash: SHA256
> > > 
> > > Hi Mike, and sorry I missed you on IRC to discuss this there. That said, 
> > > I think it's great that you took this to the mailing list, especially 
> > > seeing the conversation that has ensued.
> > > 
> > > More inline ...
> > > 
> > > On 24/03/16 01:06, Mike Perez wrote:
> > > > Hey all,
> > > > 
> > > > I've been talking to a variety of projects about lack of install 
> > > > guides. This
> > > > came from me not having a great experience with trying out projects in 
> > > > the big
> > > > tent.
> > > > 
> > > > Projects like Manila have proposed install docs [1], but they were 
> > > > rejected
> > > > by the install docs team because it's not in defcore. One of Manila's 
> > > > goals of
> > > > getting these docs accepted is to apply for the operators tag
> > > > ops:docs:install-guide [2] so that it helps their maturity level in the 
> > > > project
> > > > navigator [3].
> > > > 
> > > > Adrian Otto expressed to me having the same issue for Magnum. I think 
> > > > it's
> > > > funny that a project that gets keynote time at the OpenStack conference 
> > > > can't
> > > > be in the install docs personally.
> > > > 
> > > > As seen from the Manila review [1], the install docs team is suggesting 
> > > > these
> > > > to be put in their developer guide.
> > > 
> > > As Steve pointed out, these now have solid plans to go in. That was 
> > > because both projects opened a conversation with us and we worked with 
> > > them over time to give them the docs they required.
> > > 
> > > > 
> > > > I don't think this is a great idea. Mainly because they are for 
> > > > developers,
> > > > operators aren't going to be looking in there for install information. 
> > > > Also the
> > > > Developer doc page [4] even states "This page contains documentation 
> > > > for Python
> > > > developers, who work on OpenStack itself".
> > > 
> > > I agree, but it's a great place to start. In fact, I've just merged a 
> > > change to the Docs Contributor Guide (on the back of a previous mailing 
> > > list conversation) that explicitly states this:
> > > 
> > > http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> > > 
> > > > 
> > > > The install docs team doesn't want to be swamped with everyone in big 
> > > > tent
> > > > giving them their install docs, to be verified, and eventually likely 
> > > > to be
> > > > maintained by the install docs team.
> > > 
> > > Which is exactly why we're very selective. Sadly, documenting every big 
> > > tent project's install process is no small task.
> > 
> > I'd love to have some sort of plugin system, where teams can be
> > responsible for their own install guide repo, with a single line in the
> > RST for the install guide to have it include the repo in the build.
> > 
> > // jim
> 
> Why do we need to have one install guide? Why not separate guides for
> the peripheral projects?

That's fine too. What I really want is:

* A link into the ironic install guide from the official install guide.
* A publishing location that is not at /developer.
* To be able to meet the install guide criteria here:
  http://www.openstack.org/software/releases/liberty/components/ironic

// jim

> 
> Doug
> 
> > 
> > > 
> > > > 
> > > > However, as an operator when I go docs.openstack.org under install 
> > > > guides,
> > > > I should know how to install any of the big tent projects. These are 
> > > > accepted
> > > > projects by the Technical Committee.
> > > > 
> > > > Lets consider the bigger picture of things here. If we don't make this
> > > > information accessible, projects have poor adoption and get less 
> > > > feedback
> > > > because people can't attempt to install them to begin reporting bugs.
> > > 
> > > I agree. This has been an issue for several cycles now, but with all our 
> > > RST conversions now (mostly) behind us, I feel like we can dedicate the 
> > > Newton cycle to improving how we do things. Exactly how that happens will 
> > > need to be determined by the docs team in the Austin Design Summit, and I 
> > > strongly suggest you intend to attend that session once we have it 
> > > scheduled, as your voice is important in this conversation.
> > > 
> > > Lana
> > > 
> > > - -- 
> > > Lana Brindley
> > > Technical Writer
> > > Rackspace Cloud Builders Australia
> > > http://lanabrindley.com
> > > -BEGIN PGP SIGNATURE-
> > > Version: GnuPG v2
> > > Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
> > > 
> > > iQEcBAEBCAAGBQJW8wc7AAoJELppzVb4+KUywYMIAMr78Gw+zPp3LXyqxkQFPs9y
> > > mo/GJrfQ9OLD6CXpKSxcmvnuaHP1vHRrXPqkE02zb6YTOxV3C3CIW7hf023Dihwa
> > > uED5kL7DrkTO+xFrjClkVRpKit/ghWQ3By/V9yaYjgWQvvRy3/Y+dvjZHnrDDHE1
> > > 

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Lana Brindley]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

On 24/03/16 08:01, Doug Hellmann wrote:
> Excerpts from Lana Brindley's message of 2016-03-24 07:14:35 +1000:
>> Hi Mike, and sorry I missed you on IRC to discuss this there. That said, I 
>> think it's great that you took this to the mailing list, especially seeing 
>> the conversation that has ensued.
>>
>> More inline ...
>>
>> On 24/03/16 01:06, Mike Perez wrote:
>>> Hey all,
>>>
>>> I've been talking to a variety of projects about lack of install guides. 
>>> This
>>> came from me not having a great experience with trying out projects in the 
>>> big
>>> tent.
>>>
>>> Projects like Manila have proposed install docs [1], but they were rejected
>>> by the install docs team because it's not in defcore. One of Manila's goals 
>>> of
>>> getting these docs accepted is to apply for the operators tag
>>> ops:docs:install-guide [2] so that it helps their maturity level in the 
>>> project
>>> navigator [3].
>>>
>>> Adrian Otto expressed to me having the same issue for Magnum. I think it's
>>> funny that a project that gets keynote time at the OpenStack conference 
>>> can't
>>> be in the install docs personally.
>>>
>>> As seen from the Manila review [1], the install docs team is suggesting 
>>> these
>>> to be put in their developer guide.
>>
>> As Steve pointed out, these now have solid plans to go in. That was because 
>> both projects opened a conversation with us and we worked with them over 
>> time to give them the docs they required.
>>
>>>
>>> I don't think this is a great idea. Mainly because they are for developers,
>>> operators aren't going to be looking in there for install information. Also 
>>> the
>>> Developer doc page [4] even states "This page contains documentation for 
>>> Python
>>> developers, who work on OpenStack itself".
>>
>> I agree, but it's a great place to start. In fact, I've just merged a change 
>> to the Docs Contributor Guide (on the back of a previous mailing list 
>> conversation) that explicitly states this:
>>
>> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> 
> I think you're missing that most of us are disagreeing that it is
> a good place to start. It's fine to have the docs in a repository
> managed by the project team. It's not good at all to publish them
> under docs.o.o/developer because they are not for developers, and
> so it's confusing. This is why we ended up with a different place
> for release notes to be published, instead of just adding reno to
> the existing developer documentation build, for example.
> 

All docs need to be drafted somewhere. I don't care where that is, but make the 
suggestion of /developer because at least it's accessible there, and also 
because it's managed in the project's own repo. If you want to create a 
different place, or rename /developer to be more inclusive, I think that's a 
great idea.

>>
>>>
>>> The install docs team doesn't want to be swamped with everyone in big tent
>>> giving them their install docs, to be verified, and eventually likely to be
>>> maintained by the install docs team.
>>
>> Which is exactly why we're very selective. Sadly, documenting every big tent 
>> project's install process is no small task.
> 
> Right. The solution to that isn't to say "we aren't going to document
> it at all" or "publish the documentation somewhere less ideal",
> though, which is what it sounds like we're doing now.  It's to say

Actually, I said that I acknowledge that isn't working, and we need to find a 
different solution.

> "you are going to have to manage that document yourself, with the
> docs team answering some questions to get you started using standard
> templates for the document and build jobs".  We need a way for all
> teams to publish things they write to locations outside of their
> developer docs, without the documentation team feeling like they
> are somehow responsible for the results (or, more importantly, for
> readers of the documents to think that).

Yes, which is exactly what we'll be discussing at Summit.

> 
> I like the prominent "file a bug here" link on the new docs theme,
> so if we could reuse that but point the URL to the project's launchpad
> site instead of the documentation team's site, that would be a
> start. We may be able to do other things with the theme to further
> indicate who created the content and how to get help or report
> issues.
> 

Thanks for mentioning this, we'll take it into account during our discussions.

Lana

- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-BEGIN PGP SIGNATURE-
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCAAGBQJW8x3JAAoJELppzVb4+KUy+UoIALNBcuOjdlwogj64zZ1eqIEO
fKYBOVtmoa2KhyNxDPT+QXFxrqkd0k/mOLR9fbJF6d7qWlb7od1Jix1r+wfYkKZh
Nq0zZ8nG+tPmHR9jtRoY6cZGxXHpJRLT8IBN86rMRdryi+xwtAyzbLz1frJ3QEbb
iGr1tllU+T6vN+QChM5R7fB7MA6U3GIARBxQ1Reye/U74UeLLzZTroN20Py0OMYi

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Doug Hellmann]

Excerpts from Jim Rollenhagen's message of 2016-03-23 14:46:16 -0700:
> On Thu, Mar 24, 2016 at 07:14:35AM +1000, Lana Brindley wrote:
> > -BEGIN PGP SIGNED MESSAGE-
> > Hash: SHA256
> > 
> > Hi Mike, and sorry I missed you on IRC to discuss this there. That said, I 
> > think it's great that you took this to the mailing list, especially seeing 
> > the conversation that has ensued.
> > 
> > More inline ...
> > 
> > On 24/03/16 01:06, Mike Perez wrote:
> > > Hey all,
> > > 
> > > I've been talking to a variety of projects about lack of install guides. 
> > > This
> > > came from me not having a great experience with trying out projects in 
> > > the big
> > > tent.
> > > 
> > > Projects like Manila have proposed install docs [1], but they were 
> > > rejected
> > > by the install docs team because it's not in defcore. One of Manila's 
> > > goals of
> > > getting these docs accepted is to apply for the operators tag
> > > ops:docs:install-guide [2] so that it helps their maturity level in the 
> > > project
> > > navigator [3].
> > > 
> > > Adrian Otto expressed to me having the same issue for Magnum. I think it's
> > > funny that a project that gets keynote time at the OpenStack conference 
> > > can't
> > > be in the install docs personally.
> > > 
> > > As seen from the Manila review [1], the install docs team is suggesting 
> > > these
> > > to be put in their developer guide.
> > 
> > As Steve pointed out, these now have solid plans to go in. That was because 
> > both projects opened a conversation with us and we worked with them over 
> > time to give them the docs they required.
> > 
> > > 
> > > I don't think this is a great idea. Mainly because they are for 
> > > developers,
> > > operators aren't going to be looking in there for install information. 
> > > Also the
> > > Developer doc page [4] even states "This page contains documentation for 
> > > Python
> > > developers, who work on OpenStack itself".
> > 
> > I agree, but it's a great place to start. In fact, I've just merged a 
> > change to the Docs Contributor Guide (on the back of a previous mailing 
> > list conversation) that explicitly states this:
> > 
> > http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> > 
> > > 
> > > The install docs team doesn't want to be swamped with everyone in big tent
> > > giving them their install docs, to be verified, and eventually likely to 
> > > be
> > > maintained by the install docs team.
> > 
> > Which is exactly why we're very selective. Sadly, documenting every big 
> > tent project's install process is no small task.
> 
> I'd love to have some sort of plugin system, where teams can be
> responsible for their own install guide repo, with a single line in the
> RST for the install guide to have it include the repo in the build.
> 
> // jim

Why do we need to have one install guide? Why not separate guides for
the peripheral projects?

Doug

> 
> > 
> > > 
> > > However, as an operator when I go docs.openstack.org under install guides,
> > > I should know how to install any of the big tent projects. These are 
> > > accepted
> > > projects by the Technical Committee.
> > > 
> > > Lets consider the bigger picture of things here. If we don't make this
> > > information accessible, projects have poor adoption and get less feedback
> > > because people can't attempt to install them to begin reporting bugs.
> > 
> > I agree. This has been an issue for several cycles now, but with all our 
> > RST conversions now (mostly) behind us, I feel like we can dedicate the 
> > Newton cycle to improving how we do things. Exactly how that happens will 
> > need to be determined by the docs team in the Austin Design Summit, and I 
> > strongly suggest you intend to attend that session once we have it 
> > scheduled, as your voice is important in this conversation.
> > 
> > Lana
> > 
> > - -- 
> > Lana Brindley
> > Technical Writer
> > Rackspace Cloud Builders Australia
> > http://lanabrindley.com
> > -BEGIN PGP SIGNATURE-
> > Version: GnuPG v2
> > Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
> > 
> > iQEcBAEBCAAGBQJW8wc7AAoJELppzVb4+KUywYMIAMr78Gw+zPp3LXyqxkQFPs9y
> > mo/GJrfQ9OLD6CXpKSxcmvnuaHP1vHRrXPqkE02zb6YTOxV3C3CIW7hf023Dihwa
> > uED5kL7DrkTO+xFrjClkVRpKit/ghWQ3By/V9yaYjgWQvvRy3/Y+dvjZHnrDDHE1
> > rIxbU4PVZ0LPTxI7nNy71ffxFXW2Yn9Pl6EJnVm/iu9R+BNfRHgQ3kdqalG+Ppat
> > 9tZIGpxzi5/dTS9dTf5zN2GqYzYoDR8J6C/O/ojWyOjwcycvqWH0XboV7usLLMR8
> > 77RB/Ob8WszpbHZ6+yJF3P9hJhwhFXs8UJFcapkwaMy7wu8Lt0+etgC8nPDFj9I=
> > =hsaE
> > -END PGP 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 Development Mailing List (not 

Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - What about big tent?

[Doug Hellmann]

Excerpts from Lana Brindley's message of 2016-03-24 07:14:35 +1000:
> Hi Mike, and sorry I missed you on IRC to discuss this there. That said, I 
> think it's great that you took this to the mailing list, especially seeing 
> the conversation that has ensued.
> 
> More inline ...
> 
> On 24/03/16 01:06, Mike Perez wrote:
> > Hey all,
> > 
> > I've been talking to a variety of projects about lack of install guides. 
> > This
> > came from me not having a great experience with trying out projects in the 
> > big
> > tent.
> > 
> > Projects like Manila have proposed install docs [1], but they were rejected
> > by the install docs team because it's not in defcore. One of Manila's goals 
> > of
> > getting these docs accepted is to apply for the operators tag
> > ops:docs:install-guide [2] so that it helps their maturity level in the 
> > project
> > navigator [3].
> > 
> > Adrian Otto expressed to me having the same issue for Magnum. I think it's
> > funny that a project that gets keynote time at the OpenStack conference 
> > can't
> > be in the install docs personally.
> > 
> > As seen from the Manila review [1], the install docs team is suggesting 
> > these
> > to be put in their developer guide.
> 
> As Steve pointed out, these now have solid plans to go in. That was because 
> both projects opened a conversation with us and we worked with them over time 
> to give them the docs they required.
> 
> > 
> > I don't think this is a great idea. Mainly because they are for developers,
> > operators aren't going to be looking in there for install information. Also 
> > the
> > Developer doc page [4] even states "This page contains documentation for 
> > Python
> > developers, who work on OpenStack itself".
> 
> I agree, but it's a great place to start. In fact, I've just merged a change 
> to the Docs Contributor Guide (on the back of a previous mailing list 
> conversation) that explicitly states this:
> 
> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html

I think you're missing that most of us are disagreeing that it is
a good place to start. It's fine to have the docs in a repository
managed by the project team. It's not good at all to publish them
under docs.o.o/developer because they are not for developers, and
so it's confusing. This is why we ended up with a different place
for release notes to be published, instead of just adding reno to
the existing developer documentation build, for example.

> 
> > 
> > The install docs team doesn't want to be swamped with everyone in big tent
> > giving them their install docs, to be verified, and eventually likely to be
> > maintained by the install docs team.
> 
> Which is exactly why we're very selective. Sadly, documenting every big tent 
> project's install process is no small task.

Right. The solution to that isn't to say "we aren't going to document
it at all" or "publish the documentation somewhere less ideal",
though, which is what it sounds like we're doing now.  It's to say
"you are going to have to manage that document yourself, with the
docs team answering some questions to get you started using standard
templates for the document and build jobs".  We need a way for all
teams to publish things they write to locations outside of their
developer docs, without the documentation team feeling like they
are somehow responsible for the results (or, more importantly, for
readers of the documents to think that).

I like the prominent "file a bug here" link on the new docs theme,
so if we could reuse that but point the URL to the project's launchpad
site instead of the documentation team's site, that would be a
start. We may be able to do other things with the theme to further
indicate who created the content and how to get help or report
issues.

Doug

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Jim Rollenhagen]

On Thu, Mar 24, 2016 at 07:14:35AM +1000, Lana Brindley wrote:
> -BEGIN PGP SIGNED MESSAGE-
> Hash: SHA256
> 
> Hi Mike, and sorry I missed you on IRC to discuss this there. That said, I 
> think it's great that you took this to the mailing list, especially seeing 
> the conversation that has ensued.
> 
> More inline ...
> 
> On 24/03/16 01:06, Mike Perez wrote:
> > Hey all,
> > 
> > I've been talking to a variety of projects about lack of install guides. 
> > This
> > came from me not having a great experience with trying out projects in the 
> > big
> > tent.
> > 
> > Projects like Manila have proposed install docs [1], but they were rejected
> > by the install docs team because it's not in defcore. One of Manila's goals 
> > of
> > getting these docs accepted is to apply for the operators tag
> > ops:docs:install-guide [2] so that it helps their maturity level in the 
> > project
> > navigator [3].
> > 
> > Adrian Otto expressed to me having the same issue for Magnum. I think it's
> > funny that a project that gets keynote time at the OpenStack conference 
> > can't
> > be in the install docs personally.
> > 
> > As seen from the Manila review [1], the install docs team is suggesting 
> > these
> > to be put in their developer guide.
> 
> As Steve pointed out, these now have solid plans to go in. That was because 
> both projects opened a conversation with us and we worked with them over time 
> to give them the docs they required.
> 
> > 
> > I don't think this is a great idea. Mainly because they are for developers,
> > operators aren't going to be looking in there for install information. Also 
> > the
> > Developer doc page [4] even states "This page contains documentation for 
> > Python
> > developers, who work on OpenStack itself".
> 
> I agree, but it's a great place to start. In fact, I've just merged a change 
> to the Docs Contributor Guide (on the back of a previous mailing list 
> conversation) that explicitly states this:
> 
> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> 
> > 
> > The install docs team doesn't want to be swamped with everyone in big tent
> > giving them their install docs, to be verified, and eventually likely to be
> > maintained by the install docs team.
> 
> Which is exactly why we're very selective. Sadly, documenting every big tent 
> project's install process is no small task.

I'd love to have some sort of plugin system, where teams can be
responsible for their own install guide repo, with a single line in the
RST for the install guide to have it include the repo in the build.

// jim

> 
> > 
> > However, as an operator when I go docs.openstack.org under install guides,
> > I should know how to install any of the big tent projects. These are 
> > accepted
> > projects by the Technical Committee.
> > 
> > Lets consider the bigger picture of things here. If we don't make this
> > information accessible, projects have poor adoption and get less feedback
> > because people can't attempt to install them to begin reporting bugs.
> 
> I agree. This has been an issue for several cycles now, but with all our RST 
> conversions now (mostly) behind us, I feel like we can dedicate the Newton 
> cycle to improving how we do things. Exactly how that happens will need to be 
> determined by the docs team in the Austin Design Summit, and I strongly 
> suggest you intend to attend that session once we have it scheduled, as your 
> voice is important in this conversation.
> 
> Lana
> 
> - -- 
> Lana Brindley
> Technical Writer
> Rackspace Cloud Builders Australia
> http://lanabrindley.com
> -BEGIN PGP SIGNATURE-
> Version: GnuPG v2
> Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
> 
> iQEcBAEBCAAGBQJW8wc7AAoJELppzVb4+KUywYMIAMr78Gw+zPp3LXyqxkQFPs9y
> mo/GJrfQ9OLD6CXpKSxcmvnuaHP1vHRrXPqkE02zb6YTOxV3C3CIW7hf023Dihwa
> uED5kL7DrkTO+xFrjClkVRpKit/ghWQ3By/V9yaYjgWQvvRy3/Y+dvjZHnrDDHE1
> rIxbU4PVZ0LPTxI7nNy71ffxFXW2Yn9Pl6EJnVm/iu9R+BNfRHgQ3kdqalG+Ppat
> 9tZIGpxzi5/dTS9dTf5zN2GqYzYoDR8J6C/O/ojWyOjwcycvqWH0XboV7usLLMR8
> 77RB/Ob8WszpbHZ6+yJF3P9hJhwhFXs8UJFcapkwaMy7wu8Lt0+etgC8nPDFj9I=
> =hsaE
> -END PGP 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 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] Our Install Guides Only Cover Defcore - What about big tent?

[Lana Brindley]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

Hi Mike, and sorry I missed you on IRC to discuss this there. That said, I 
think it's great that you took this to the mailing list, especially seeing the 
conversation that has ensued.

More inline ...

On 24/03/16 01:06, Mike Perez wrote:
> Hey all,
> 
> I've been talking to a variety of projects about lack of install guides. This
> came from me not having a great experience with trying out projects in the big
> tent.
> 
> Projects like Manila have proposed install docs [1], but they were rejected
> by the install docs team because it's not in defcore. One of Manila's goals of
> getting these docs accepted is to apply for the operators tag
> ops:docs:install-guide [2] so that it helps their maturity level in the 
> project
> navigator [3].
> 
> Adrian Otto expressed to me having the same issue for Magnum. I think it's
> funny that a project that gets keynote time at the OpenStack conference can't
> be in the install docs personally.
> 
> As seen from the Manila review [1], the install docs team is suggesting these
> to be put in their developer guide.

As Steve pointed out, these now have solid plans to go in. That was because 
both projects opened a conversation with us and we worked with them over time 
to give them the docs they required.

> 
> I don't think this is a great idea. Mainly because they are for developers,
> operators aren't going to be looking in there for install information. Also 
> the
> Developer doc page [4] even states "This page contains documentation for 
> Python
> developers, who work on OpenStack itself".

I agree, but it's a great place to start. In fact, I've just merged a change to 
the Docs Contributor Guide (on the back of a previous mailing list 
conversation) that explicitly states this:

http://docs.openstack.org/contributor-guide/quickstart/new-projects.html

> 
> The install docs team doesn't want to be swamped with everyone in big tent
> giving them their install docs, to be verified, and eventually likely to be
> maintained by the install docs team.

Which is exactly why we're very selective. Sadly, documenting every big tent 
project's install process is no small task.

> 
> However, as an operator when I go docs.openstack.org under install guides,
> I should know how to install any of the big tent projects. These are accepted
> projects by the Technical Committee.
> 
> Lets consider the bigger picture of things here. If we don't make this
> information accessible, projects have poor adoption and get less feedback
> because people can't attempt to install them to begin reporting bugs.

I agree. This has been an issue for several cycles now, but with all our RST 
conversions now (mostly) behind us, I feel like we can dedicate the Newton 
cycle to improving how we do things. Exactly how that happens will need to be 
determined by the docs team in the Austin Design Summit, and I strongly suggest 
you intend to attend that session once we have it scheduled, as your voice is 
important in this conversation.

Lana

- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-BEGIN PGP SIGNATURE-
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCAAGBQJW8wc7AAoJELppzVb4+KUywYMIAMr78Gw+zPp3LXyqxkQFPs9y
mo/GJrfQ9OLD6CXpKSxcmvnuaHP1vHRrXPqkE02zb6YTOxV3C3CIW7hf023Dihwa
uED5kL7DrkTO+xFrjClkVRpKit/ghWQ3By/V9yaYjgWQvvRy3/Y+dvjZHnrDDHE1
rIxbU4PVZ0LPTxI7nNy71ffxFXW2Yn9Pl6EJnVm/iu9R+BNfRHgQ3kdqalG+Ppat
9tZIGpxzi5/dTS9dTf5zN2GqYzYoDR8J6C/O/ojWyOjwcycvqWH0XboV7usLLMR8
77RB/Ob8WszpbHZ6+yJF3P9hJhwhFXs8UJFcapkwaMy7wu8Lt0+etgC8nPDFj9I=
=hsaE
-END PGP 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] Our Install Guides Only Cover Defcore - What about big tent?

[Flavio Percoco]

On 23/03/16 15:00 -0400, Doug Hellmann wrote:

Excerpts from Mike Perez's message of 2016-03-23 08:06:28 -0700:

Hey all,

I've been talking to a variety of projects about lack of install guides. This
came from me not having a great experience with trying out projects in the big
tent.

Projects like Manila have proposed install docs [1], but they were rejected
by the install docs team because it's not in defcore. One of Manila's goals of
getting these docs accepted is to apply for the operators tag
ops:docs:install-guide [2] so that it helps their maturity level in the project
navigator [3].

Adrian Otto expressed to me having the same issue for Magnum. I think it's
funny that a project that gets keynote time at the OpenStack conference can't
be in the install docs personally.

As seen from the Manila review [1], the install docs team is suggesting these
to be put in their developer guide.

I don't think this is a great idea. Mainly because they are for developers,
operators aren't going to be looking in there for install information. Also the
Developer doc page [4] even states "This page contains documentation for Python
developers, who work on OpenStack itself".

The install docs team doesn't want to be swamped with everyone in big tent
giving them their install docs, to be verified, and eventually likely to be
maintained by the install docs team.

However, as an operator when I go docs.openstack.org under install guides,
I should know how to install any of the big tent projects. These are accepted
projects by the Technical Committee.

Lets consider the bigger picture of things here. If we don't make this
information accessible, projects have poor adoption and get less feedback
because people can't attempt to install them to begin reporting bugs.

Proposal: if the install docs team doesn't want them in the install docs repo
and instead to live in tree of the project itself before it's in defcore, can
we at least make the install guides for all big tent projects accessible
at docs.openstack.org under install guides?


This seems like a reasonable compromise. We can either handle them using
separate manual repos, or as Julien points out we could include them in
the tree with the code and publish them separately like we're doing with
release notes.


I think merging it in tree and publsihing them separatedly (or collecting them
under the same link) would be better.

FWIW, Zaqar had the same issue as other projects and the team ended up merging
the guide in the tree.

Flavio


Doug




[1] - https://review.openstack.org/#/c/213756/
[2] - 
http://git.openstack.org/cgit/openstack/ops-tags-team/tree/descriptions/ops-docs-install-guide.rst
[3] - http://www.openstack.org/software/releases/liberty/components/manila
[4] - http://docs.openstack.org/developer/openstack-projects.html



__
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


--
@flaper87
Flavio Percoco


signature.asc
Description: PGP 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] Our Install Guides Only Cover Defcore - What about big tent?

[Russell Bryant]

On Wed, Mar 23, 2016 at 11:06 AM, Mike Perez  wrote:

> Hey all,
>
> I've been talking to a variety of projects about lack of install guides.
> This
> came from me not having a great experience with trying out projects in the
> big
> tent.
>
> Projects like Manila have proposed install docs [1], but they were rejected
> by the install docs team because it's not in defcore. One of Manila's
> goals of
> getting these docs accepted is to apply for the operators tag
> ops:docs:install-guide [2] so that it helps their maturity level in the
> project
> navigator [3].
>
> Adrian Otto expressed to me having the same issue for Magnum. I think it's
> funny that a project that gets keynote time at the OpenStack conference
> can't
> be in the install docs personally.
>
> As seen from the Manila review [1], the install docs team is suggesting
> these
> to be put in their developer guide.
>
> I don't think this is a great idea. Mainly because they are for developers,
> operators aren't going to be looking in there for install information.
> Also the
> Developer doc page [4] even states "This page contains documentation for
> Python
> developers, who work on OpenStack itself".
>
> The install docs team doesn't want to be swamped with everyone in big tent
> giving them their install docs, to be verified, and eventually likely to be
> maintained by the install docs team.
>
> However, as an operator when I go docs.openstack.org under install guides,
> I should know how to install any of the big tent projects. These are
> accepted
> projects by the Technical Committee.
>
> Lets consider the bigger picture of things here. If we don't make this
> information accessible, projects have poor adoption and get less feedback
> because people can't attempt to install them to begin reporting bugs.
>
> Proposal: if the install docs team doesn't want them in the install docs
> repo
> and instead to live in tree of the project itself before it's in defcore,
> can
> we at least make the install guides for all big tent projects accessible
> at docs.openstack.org under install guides?
>
>
> [1] - https://review.openstack.org/#/c/213756/
> [2] -
> http://git.openstack.org/cgit/openstack/ops-tags-team/tree/descriptions/ops-docs-install-guide.rst
> [3] - http://www.openstack.org/software/releases/liberty/components/manila
> [4] - http://docs.openstack.org/developer/openstack-projects.html
>

​FWIW, the same issue applies to other official docs.  In particular, I'm
thinking of the networking guide.

http://docs.openstack.org/liberty/networking-guide/

The networking guide is *fantastic*, but it's limited to covering only
ML2+OVS and ML2+LB.  Coverage for other backends is currently considered
out of scope, leaving no official place to put equivalent documentation
except in dev docs.

We got pushback on documenting OVN there, so we've been putting everything
in our dev docs, instead.  For example:

http://docs.openstack.org/developer/networking-ovn/install.html
http://docs.openstack.org/developer/networking-ovn/refarch.html

​It'd be nice to have somewhere else to publish these operator-oriented
docs.

-- 
Russell Bryant
__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Doug Hellmann]

Excerpts from Mike Perez's message of 2016-03-23 08:06:28 -0700:
> Hey all,
> 
> I've been talking to a variety of projects about lack of install guides. This
> came from me not having a great experience with trying out projects in the big
> tent.
> 
> Projects like Manila have proposed install docs [1], but they were rejected
> by the install docs team because it's not in defcore. One of Manila's goals of
> getting these docs accepted is to apply for the operators tag
> ops:docs:install-guide [2] so that it helps their maturity level in the 
> project
> navigator [3].
> 
> Adrian Otto expressed to me having the same issue for Magnum. I think it's
> funny that a project that gets keynote time at the OpenStack conference can't
> be in the install docs personally.
> 
> As seen from the Manila review [1], the install docs team is suggesting these
> to be put in their developer guide.
> 
> I don't think this is a great idea. Mainly because they are for developers,
> operators aren't going to be looking in there for install information. Also 
> the
> Developer doc page [4] even states "This page contains documentation for 
> Python
> developers, who work on OpenStack itself".
> 
> The install docs team doesn't want to be swamped with everyone in big tent
> giving them their install docs, to be verified, and eventually likely to be
> maintained by the install docs team.
> 
> However, as an operator when I go docs.openstack.org under install guides,
> I should know how to install any of the big tent projects. These are accepted
> projects by the Technical Committee.
> 
> Lets consider the bigger picture of things here. If we don't make this
> information accessible, projects have poor adoption and get less feedback
> because people can't attempt to install them to begin reporting bugs.
> 
> Proposal: if the install docs team doesn't want them in the install docs repo
> and instead to live in tree of the project itself before it's in defcore, can
> we at least make the install guides for all big tent projects accessible
> at docs.openstack.org under install guides?

This seems like a reasonable compromise. We can either handle them using
separate manual repos, or as Julien points out we could include them in
the tree with the code and publish them separately like we're doing with
release notes.

Doug

> 
> 
> [1] - https://review.openstack.org/#/c/213756/
> [2] - 
> http://git.openstack.org/cgit/openstack/ops-tags-team/tree/descriptions/ops-docs-install-guide.rst
> [3] - http://www.openstack.org/software/releases/liberty/components/manila
> [4] - http://docs.openstack.org/developer/openstack-projects.html
> 

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Steve Gordon]

- Original Message -
> From: "Mike Perez" <thin...@gmail.com>
> To: "OpenStack Development Mailing List (not for usage questions)" 
> <openstack-dev@lists.openstack.org>
> Sent: Wednesday, March 23, 2016 12:24:55 PM
> Subject: Re: [openstack-dev] [docs] Our Install Guides Only Cover Defcore - 
> What  about big tent?
> 
> On 12:05 Mar 23, Steve Gordon wrote:
> 
> > Did you look at the link I provided above?:
> > 
> > http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst
> > 
> > This content is merged.
> 
> Thanks Steve. So is this no longer a requirement that a project has to be
> considered by the Defcore group in order to be in the install docs as Lana
> has
> required previously?

I'll not put words in Lana's mouth, but my take based on what happens in 
practice is that the docs team - and more specifically the install guide 
subteam - remain focused on defcore projects only but are willing to be 
flexible where someone from a non-defcore big tent project is willing to stand 
up and own the work of creating and maintaining the docs in the guide - though 
they do expect a blueprint/spec to propose adding a new project to the install 
guide and that the project be packaged for the distros the guide covers. The 
bottom line is someone involved with the project being added needs to own the 
work as the regular docs folks are not in a position to cover every project in 
the big tent.

In the case of Manila this has happened and the results will appear in the 
Mitaka guide, while in the case of Magnum this didn't happen - at least until 
very recently, hence it being pushed to Newton. The spec review for that is 
here: 

https://review.openstack.org/#/c/289994/

Thanks,

Steve

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Julien Danjou]

On Wed, Mar 23 2016, Mike Perez wrote:

> As seen from the Manila review [1], the install docs team is suggesting these
> to be put in their developer guide.
>
> I don't think this is a great idea. Mainly because they are for developers,
> operators aren't going to be looking in there for install information. Also 
> the
> Developer doc page [4] even states "This page contains documentation for 
> Python
> developers, who work on OpenStack itself".
>
> The install docs team doesn't want to be swamped with everyone in big tent
> giving them their install docs, to be verified, and eventually likely to be
> maintained by the install docs team.

So what I've been pushing for a few years now (and I keep trying) is to
have the user documentation be required as part of the code that is
contributed by the project – just like we did for unit tests, and just
like we finally do with functional tests (e.g. tempest-lib).

We did that for day 1 with Gnocchi, and so far it works pretty far:

  http://gnocchi.xyz/install.html

The project is probably (made) less complex than e.g. Neutron or Manila
to deploy, but it should be possible to achieve some of that for most
projects. Actually, believe it or not, many open-source projects out
there also do that with great success.

That doc-is-mandatory-with-your-code policy does not prevent the doc
team to do its job. But it makes sure that the people writing the doc
are the same that wrote the code, which brings a few interesting side
effects:

- you can spot mistakes in the code or the doc just by seeing the
  disparity between the two
- you are sure that the feature is well understood by the doc writer and
  that there are no misinterpretation on what $option does
- the documentation is always up-to-date
- it forces the developer to think twice before implementing things that
  are too complicated to deploy since they'll have to write and explain
  how to do it

Then, the doc team is free to jump-in at anytime and review the doc.
Though I never saw anyone from the doc team review doc on Gnocchi – but
I guess they're too busy with other projects making them writing their
doc. :-)

Now, it's very likely that we'll move that policy to Aodh and Ceilometer
during the next cycle.

Continuing to address OpenStack and its documentation as a single and
unified project, while we are in a Big Tent mode, hoping it's gonna
scale, seems to me unrealistic.

Cheers,
-- 
Julien Danjou
/* Free Software hacker
   https://julien.danjou.info */


signature.asc
Description: PGP 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] Our Install Guides Only Cover Defcore - What about big tent?

[Mike Perez]

On 12:05 Mar 23, Steve Gordon wrote:
 
> Did you look at the link I provided above?:
> 
> http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst
> 
> This content is merged.

Thanks Steve. So is this no longer a requirement that a project has to be
considered by the Defcore group in order to be in the install docs as Lana has
required previously?

-- 
Mike Perez

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Hayes, Graham]

On 23/03/2016 16:12, Steve Gordon wrote:
> - Original Message -
>> From: "Steve Gordon" 
>> To: "OpenStack Development Mailing List (not for usage questions)" 
>> 
>>
>> - Original Message -
>>> From: "Graham Hayes" ha...@hpe.com>
>>> To: "OpenStack Development Mailing List (not for usage questions)"
>>> 
>>>
>>> On 23/03/2016 15:37, Steve Gordon wrote:
 - Original Message -
> From: "Mike Perez" 
> To: "OpenStack Development Mailing List"
> 
>
> Hey all,
>
> I've been talking to a variety of projects about lack of install guides.
> This
> came from me not having a great experience with trying out projects in
> the
> big
> tent.
>
> Projects like Manila have proposed install docs [1], but they were
> rejected
> by the install docs team because it's not in defcore. One of Manila's
> goals
> of
> getting these docs accepted is to apply for the operators tag
> ops:docs:install-guide [2] so that it helps their maturity level in the
> project
> navigator [3].
>
> Adrian Otto expressed to me having the same issue for Magnum. I think
> it's
> funny that a project that gets keynote time at the OpenStack conference
> can't
> be in the install docs personally.

 Just two minor clarifications here:

 * Manila install docs are actively being worked on for inclusion in the
 Mitaka version of the guide:
 http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst

 * Magnum install docs were only very recently proposed here -
 https://review.openstack.org/#/c/288580/ - nobody is saying they can't be
 in the install guide assuming someone is willing to write/maintain them,
 but until now it wasn't clear anyone was.

 I certainly think a better system for linking out-of-tree install docs
 for
 big tent projects would be worth pursuing, but regardless of where it
 lives someone still has to write/maintain that user-orientated content.
 For those that have someone actively doing this on an ongoing basis they
 already have a path to inclusion in the guide (or at least, it seems that
 way based on the cases I am familiar with like those above).

 Are there examples of projects that have this user orientated install
 documentation written but are actively being rejected from including it
 in
 the install guide (in the Magnum case it has been pushed out to Newton as
 it was a late submission, not rejected permanently)?

>>>
>>> the linked review - https://review.openstack.org/#/c/213756/
>>
>> Did you look at the link I provided above?:
>>
>> http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst
>>
>> This content is merged.
>>
>> -Steve
>
> Here is the Mitaka spec review for the proposal to add Magnum to the guide: 
> https://review.openstack.org/#/c/275200/
> Here is the Mitaka review to add the Magnum content to the guide: 
> https://review.openstack.org/#/c/273724/

And as I said, if this has changed, that is great.

At the last time I checked docs were def-core only.

> -Steve
>
> __
> 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] Our Install Guides Only Cover Defcore - What about big tent?

[Steve Gordon]

- Original Message -
> From: "Steve Gordon" 
> To: "OpenStack Development Mailing List (not for usage questions)" 
> 
> 
> - Original Message -
> > From: "Steve Gordon" 
> > To: "OpenStack Development Mailing List (not for usage questions)"
> > 
> > 
> > - Original Message -
> > > From: "Graham Hayes" ha...@hpe.com>
> > > To: "OpenStack Development Mailing List (not for usage questions)"
> > > 
> > > 
> > > On 23/03/2016 15:37, Steve Gordon wrote:
> > > > - Original Message -
> > > >> From: "Mike Perez" 
> > > >> To: "OpenStack Development Mailing List"
> > > >> 
> > > >>
> > > >> Hey all,
> > > >>
> > > >> I've been talking to a variety of projects about lack of install
> > > >> guides.
> > > >> This
> > > >> came from me not having a great experience with trying out projects in
> > > >> the
> > > >> big
> > > >> tent.
> > > >>
> > > >> Projects like Manila have proposed install docs [1], but they were
> > > >> rejected
> > > >> by the install docs team because it's not in defcore. One of Manila's
> > > >> goals
> > > >> of
> > > >> getting these docs accepted is to apply for the operators tag
> > > >> ops:docs:install-guide [2] so that it helps their maturity level in
> > > >> the
> > > >> project
> > > >> navigator [3].
> > > >>
> > > >> Adrian Otto expressed to me having the same issue for Magnum. I think
> > > >> it's
> > > >> funny that a project that gets keynote time at the OpenStack
> > > >> conference
> > > >> can't
> > > >> be in the install docs personally.
> > > >
> > > > Just two minor clarifications here:
> > > >
> > > > * Manila install docs are actively being worked on for inclusion in the
> > > > Mitaka version of the guide:
> > > > http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst
> > > >
> > > > * Magnum install docs were only very recently proposed here -
> > > > https://review.openstack.org/#/c/288580/ - nobody is saying they can't
> > > > be
> > > > in the install guide assuming someone is willing to write/maintain
> > > > them,
> > > > but until now it wasn't clear anyone was.
> > > >
> > > > I certainly think a better system for linking out-of-tree install docs
> > > > for
> > > > big tent projects would be worth pursuing, but regardless of where it
> > > > lives someone still has to write/maintain that user-orientated content.
> > > > For those that have someone actively doing this on an ongoing basis
> > > > they
> > > > already have a path to inclusion in the guide (or at least, it seems
> > > > that
> > > > way based on the cases I am familiar with like those above).
> > > >
> > > > Are there examples of projects that have this user orientated install
> > > > documentation written but are actively being rejected from including it
> > > > in
> > > > the install guide (in the Magnum case it has been pushed out to Newton
> > > > as
> > > > it was a late submission, not rejected permanently)?
> > > >
> > > 
> > > the linked review - https://review.openstack.org/#/c/213756/
> > 
> > Did you look at the link I provided above?:
> > 
> > http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst
> > 
> > This content is merged.
> > 
> > -Steve
> 
> Here is the Mitaka spec review for the proposal to add Magnum to the guide:
> https://review.openstack.org/#/c/275200/
> Here is the Mitaka review to add the Magnum content to the guide:
> https://review.openstack.org/#/c/273724/
> 
> -Steve

Sorry, I mean Manila above obviously (same project as the 213756 review was 
for) - the Magnum proposal will likely be looked at for Newton (assuming the 
owner keeps working on it).

-Steve

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Steve Gordon]

- Original Message -
> From: "Steve Gordon" 
> To: "OpenStack Development Mailing List (not for usage questions)" 
> 
> 
> - Original Message -
> > From: "Graham Hayes" ha...@hpe.com>
> > To: "OpenStack Development Mailing List (not for usage questions)"
> > 
> > 
> > On 23/03/2016 15:37, Steve Gordon wrote:
> > > - Original Message -
> > >> From: "Mike Perez" 
> > >> To: "OpenStack Development Mailing List"
> > >> 
> > >>
> > >> Hey all,
> > >>
> > >> I've been talking to a variety of projects about lack of install guides.
> > >> This
> > >> came from me not having a great experience with trying out projects in
> > >> the
> > >> big
> > >> tent.
> > >>
> > >> Projects like Manila have proposed install docs [1], but they were
> > >> rejected
> > >> by the install docs team because it's not in defcore. One of Manila's
> > >> goals
> > >> of
> > >> getting these docs accepted is to apply for the operators tag
> > >> ops:docs:install-guide [2] so that it helps their maturity level in the
> > >> project
> > >> navigator [3].
> > >>
> > >> Adrian Otto expressed to me having the same issue for Magnum. I think
> > >> it's
> > >> funny that a project that gets keynote time at the OpenStack conference
> > >> can't
> > >> be in the install docs personally.
> > >
> > > Just two minor clarifications here:
> > >
> > > * Manila install docs are actively being worked on for inclusion in the
> > > Mitaka version of the guide:
> > > http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst
> > >
> > > * Magnum install docs were only very recently proposed here -
> > > https://review.openstack.org/#/c/288580/ - nobody is saying they can't be
> > > in the install guide assuming someone is willing to write/maintain them,
> > > but until now it wasn't clear anyone was.
> > >
> > > I certainly think a better system for linking out-of-tree install docs
> > > for
> > > big tent projects would be worth pursuing, but regardless of where it
> > > lives someone still has to write/maintain that user-orientated content.
> > > For those that have someone actively doing this on an ongoing basis they
> > > already have a path to inclusion in the guide (or at least, it seems that
> > > way based on the cases I am familiar with like those above).
> > >
> > > Are there examples of projects that have this user orientated install
> > > documentation written but are actively being rejected from including it
> > > in
> > > the install guide (in the Magnum case it has been pushed out to Newton as
> > > it was a late submission, not rejected permanently)?
> > >
> > 
> > the linked review - https://review.openstack.org/#/c/213756/
> 
> Did you look at the link I provided above?:
> 
> http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst
> 
> This content is merged.
> 
> -Steve

Here is the Mitaka spec review for the proposal to add Magnum to the guide: 
https://review.openstack.org/#/c/275200/
Here is the Mitaka review to add the Magnum content to the guide: 
https://review.openstack.org/#/c/273724/

-Steve

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Steve Gordon]

- Original Message -
> From: "Graham Hayes" 
> To: "OpenStack Development Mailing List (not for usage questions)" 
> 
> 
> On 23/03/2016 15:37, Steve Gordon wrote:
> > - Original Message -
> >> From: "Mike Perez" 
> >> To: "OpenStack Development Mailing List"
> >> 
> >>
> >> Hey all,
> >>
> >> I've been talking to a variety of projects about lack of install guides.
> >> This
> >> came from me not having a great experience with trying out projects in the
> >> big
> >> tent.
> >>
> >> Projects like Manila have proposed install docs [1], but they were
> >> rejected
> >> by the install docs team because it's not in defcore. One of Manila's
> >> goals
> >> of
> >> getting these docs accepted is to apply for the operators tag
> >> ops:docs:install-guide [2] so that it helps their maturity level in the
> >> project
> >> navigator [3].
> >>
> >> Adrian Otto expressed to me having the same issue for Magnum. I think it's
> >> funny that a project that gets keynote time at the OpenStack conference
> >> can't
> >> be in the install docs personally.
> >
> > Just two minor clarifications here:
> >
> > * Manila install docs are actively being worked on for inclusion in the
> > Mitaka version of the guide:
> > http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst
> >
> > * Magnum install docs were only very recently proposed here -
> > https://review.openstack.org/#/c/288580/ - nobody is saying they can't be
> > in the install guide assuming someone is willing to write/maintain them,
> > but until now it wasn't clear anyone was.
> >
> > I certainly think a better system for linking out-of-tree install docs for
> > big tent projects would be worth pursuing, but regardless of where it
> > lives someone still has to write/maintain that user-orientated content.
> > For those that have someone actively doing this on an ongoing basis they
> > already have a path to inclusion in the guide (or at least, it seems that
> > way based on the cases I am familiar with like those above).
> >
> > Are there examples of projects that have this user orientated install
> > documentation written but are actively being rejected from including it in
> > the install guide (in the Magnum case it has been pushed out to Newton as
> > it was a late submission, not rejected permanently)?
> >
> 
> the linked review - https://review.openstack.org/#/c/213756/

Did you look at the link I provided above?:

http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst

This content is merged.

-Steve

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Hayes, Graham]

On 23/03/2016 15:37, Steve Gordon wrote:
> - Original Message -
>> From: "Mike Perez" 
>> To: "OpenStack Development Mailing List" 
>>
>> Hey all,
>>
>> I've been talking to a variety of projects about lack of install guides. This
>> came from me not having a great experience with trying out projects in the
>> big
>> tent.
>>
>> Projects like Manila have proposed install docs [1], but they were rejected
>> by the install docs team because it's not in defcore. One of Manila's goals
>> of
>> getting these docs accepted is to apply for the operators tag
>> ops:docs:install-guide [2] so that it helps their maturity level in the
>> project
>> navigator [3].
>>
>> Adrian Otto expressed to me having the same issue for Magnum. I think it's
>> funny that a project that gets keynote time at the OpenStack conference can't
>> be in the install docs personally.
>
> Just two minor clarifications here:
>
> * Manila install docs are actively being worked on for inclusion in the 
> Mitaka version of the guide: 
> http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst
>
> * Magnum install docs were only very recently proposed here - 
> https://review.openstack.org/#/c/288580/ - nobody is saying they can't be in 
> the install guide assuming someone is willing to write/maintain them, but 
> until now it wasn't clear anyone was.
>
> I certainly think a better system for linking out-of-tree install docs for 
> big tent projects would be worth pursuing, but regardless of where it lives 
> someone still has to write/maintain that user-orientated content. For those 
> that have someone actively doing this on an ongoing basis they already have a 
> path to inclusion in the guide (or at least, it seems that way based on the 
> cases I am familiar with like those above).
>
> Are there examples of projects that have this user orientated install 
> documentation written but are actively being rejected from including it in 
> the install guide (in the Magnum case it has been pushed out to Newton as it 
> was a late submission, not rejected permanently)?
>

the linked review - https://review.openstack.org/#/c/213756/

Lana Brindley
Aug 18, 2015
Patch Set 1: Code-Review-2
The Install Guide covers defcore projects only, sorry.

Lana Brindley
Aug 27, 2015
Abandoned
This content belongs in the Manila /developer docs.

If this has changed - that is great, I will start getting our docs
together for the guide, but seeing patches like this is why we didn't
try before.

> -Steve
>
> __
> 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] Our Install Guides Only Cover Defcore - What about big tent?

[Mike Perez]

On 11:34 Mar 23, Steve Gordon wrote:
 
> Are there examples of projects that have this user orientated install
> documentation written but are actively being rejected from including it in
> the install guide (in the Magnum case it has been pushed out to Newton as it
> was a late submission, not rejected permanently)?

The Manila case was my example. It was abandoned by Lana because:

"The Install Guide covers defcore projects only, sorry." [1] and see a more
detailed explanation [2].

If this is no longer the case, I might've missed something and would appreciate
where it's mentioned directions are changing.

[1] - https://review.openstack.org/#/c/213756/
[2] - 
http://lists.openstack.org/pipermail/openstack-docs/2015-December/008062.html

-- 
Mike Perez

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Steve Gordon]

- Original Message -
> From: "Mike Perez" 
> To: "OpenStack Development Mailing List" 
> 
> Hey all,
> 
> I've been talking to a variety of projects about lack of install guides. This
> came from me not having a great experience with trying out projects in the
> big
> tent.
> 
> Projects like Manila have proposed install docs [1], but they were rejected
> by the install docs team because it's not in defcore. One of Manila's goals
> of
> getting these docs accepted is to apply for the operators tag
> ops:docs:install-guide [2] so that it helps their maturity level in the
> project
> navigator [3].
> 
> Adrian Otto expressed to me having the same issue for Magnum. I think it's
> funny that a project that gets keynote time at the OpenStack conference can't
> be in the install docs personally.

Just two minor clarifications here:

* Manila install docs are actively being worked on for inclusion in the Mitaka 
version of the guide: 
http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/install-guide/source/manila.rst

* Magnum install docs were only very recently proposed here - 
https://review.openstack.org/#/c/288580/ - nobody is saying they can't be in 
the install guide assuming someone is willing to write/maintain them, but until 
now it wasn't clear anyone was.

I certainly think a better system for linking out-of-tree install docs for big 
tent projects would be worth pursuing, but regardless of where it lives someone 
still has to write/maintain that user-orientated content. For those that have 
someone actively doing this on an ongoing basis they already have a path to 
inclusion in the guide (or at least, it seems that way based on the cases I am 
familiar with like those above).

Are there examples of projects that have this user orientated install 
documentation written but are actively being rejected from including it in the 
install guide (in the Magnum case it has been pushed out to Newton as it was a 
late submission, not rejected permanently)?

-Steve

__
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] Our Install Guides Only Cover Defcore - What about big tent?

[Mike Perez]

Hey all,

I've been talking to a variety of projects about lack of install guides. This
came from me not having a great experience with trying out projects in the big
tent.

Projects like Manila have proposed install docs [1], but they were rejected
by the install docs team because it's not in defcore. One of Manila's goals of
getting these docs accepted is to apply for the operators tag
ops:docs:install-guide [2] so that it helps their maturity level in the project
navigator [3].

Adrian Otto expressed to me having the same issue for Magnum. I think it's
funny that a project that gets keynote time at the OpenStack conference can't
be in the install docs personally.

As seen from the Manila review [1], the install docs team is suggesting these
to be put in their developer guide.

I don't think this is a great idea. Mainly because they are for developers,
operators aren't going to be looking in there for install information. Also the
Developer doc page [4] even states "This page contains documentation for Python
developers, who work on OpenStack itself".

The install docs team doesn't want to be swamped with everyone in big tent
giving them their install docs, to be verified, and eventually likely to be
maintained by the install docs team.

However, as an operator when I go docs.openstack.org under install guides,
I should know how to install any of the big tent projects. These are accepted
projects by the Technical Committee.

Lets consider the bigger picture of things here. If we don't make this
information accessible, projects have poor adoption and get less feedback
because people can't attempt to install them to begin reporting bugs.

Proposal: if the install docs team doesn't want them in the install docs repo
and instead to live in tree of the project itself before it's in defcore, can
we at least make the install guides for all big tent projects accessible
at docs.openstack.org under install guides?


[1] - https://review.openstack.org/#/c/213756/
[2] - 
http://git.openstack.org/cgit/openstack/ops-tags-team/tree/descriptions/ops-docs-install-guide.rst
[3] - http://www.openstack.org/software/releases/liberty/components/manila
[4] - http://docs.openstack.org/developer/openstack-projects.html

-- 
Mike Perez

__
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