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

Amrith Kumar amrith at tesora.com
Wed Apr 13 18:01:25 UTC 2016


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:aj at suse.com]
> Sent: Wednesday, April 13, 2016 1:46 PM
> To: Amrith Kumar <amrith at tesora.com>; OpenStack Development Mailing List
> (not for usage questions) <openstack-dev at lists.openstack.org>
> Cc: mkassawara at gmail.com; Lana Brindley <openstack at lanabrindley.com>; Mike
> Perez <mike at openstack.org>; openstack-docs at 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:aj at suse.com]
> >> Sent: Monday, April 04, 2016 2:42 PM
> >> To: OpenStack Development Mailing List (not for usage questions)
> >> <openstack-dev at 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-request at lists.openstack.org?subject:unsubscribe
> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
> 
> 
> --
>  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




More information about the OpenStack-dev mailing list