Open Stack

I think our audience is most familiar and comfortable with distribution
packages. Although not perfect, packages let our audience focus on the
OpenStack configuration necessary to launch a VM rather than fumbling
through Python dependencies, building init scripts, getting rootwrap
working, etc. I think we need to pursue documenting a source installation
option, but probably make it cater to people who want to take the next step
toward customizing and automating a production deployment. In other words,
the source installation option should consider an audience with more
experience and therefore contain somewhat general instructions that require
less extensive testing for each release.

In addition to using packages, maintaining a consistent structure for each
service also benefits our audience because they can glean configuration
similarities among services... perhaps simply through repetition. For
example... create the SQL database, create Identity service entities,
install packages, configure the service, synchronize database schema, start
the service, and verify operation of the service. Allowing projects to
provide installation content outside of the central installation guide
primarily impacts the consistent structure, but also impacts the ability
for the installation guide team (already very small and stretched very
thin) to continue maintaining the guide in a proactive fashion by
validating it prior to each release rather than waiting for our audience to
open bugs, become frustrated, and ultimately decide against using
OpenStack. The installation guide is usually the first thing newcomers
stumble upon and a great experience benefits everyone.


On Tue, Dec 8, 2015 at 10:27 AM, Anne Gentle <annegentle at justwriteclick.com>
wrote:

>
>
> On Tue, Dec 8, 2015 at 10:05 AM, Matt Kassawara <mkassawara at gmail.com>
> wrote:
>
>> I think maintaining consistency and addressing issues becomes a problem
>> if each project contains its own installation procedures.
>>
>
> Okay, let's describe this system further. So for you the bar would be
> packaging resources for all four distros? Then you'd support a second
> install guide dir in the openstack-manuals repo? Or additional chapters in
> the existing install guide?
>
> Can you discuss at the next install team meeting and let us know the
> team's recommendations for defining the inclusion -- what, where, by when,
> and how? Also does the install team envision being able to activate on this
> for the mitaka release? Is there a deadline for when packages would need to
> be tested, for example? We need to give Ben and other teams guidance by
> milestone-2, mid-January, if possible.
>
> I can support what the install guide team thinks is possible, once I
> understand it.
>
> Thanks,
> Anne
>
>
>>
>> On Tue, Dec 8, 2015 at 8:13 AM, Anne Gentle <
>> annegentle at justwriteclick.com> wrote:
>>
>>>
>>>
>>> On Mon, Dec 7, 2015 at 1:44 PM, Ben Swartzlander <ben at swartzlander.org>
>>> wrote:
>>>
>>>> On 12/07/2015 10:42 AM, Anne Gentle wrote:
>>>>
>>>>>
>>>>>
>>>>> On Mon, Dec 7, 2015 at 9:36 AM, Ben Swartzlander <ben at swartzlander.org
>>>>> <mailto:ben at swartzlander.org>> wrote:
>>>>>
>>>>>     Hello docs team, when we submitted the install guide for Manila [1]
>>>>>     in Liberty it was rejected because at the time only defcore
>>>>> projects
>>>>>     were covered by the guide. Has that policy changed yet?
>>>>>
>>>>>
>>>>> I don't believe it will this release.
>>>>>
>>>>>     If not, I would like to hear your recommendation for where the
>>>>>     Manila install guide should go. The foundation's project navigator
>>>>>     [2] counts the lack of an install guide as a mark against Manila.
>>>>>
>>>>>
>>>>> Have you published the RST files from that original patch from your own
>>>>> doc/source directory? That should count.
>>>>>
>>>>
>>>> No we haven't. It's an option, but not one that I favor because we're
>>>> trying to get all the docs (except dev docs) out of the code tree and into
>>>> the manuals project where they belong.
>>>>
>>>>     I'm willing to resubmit the install guide content wherever it needs
>>>>>     to go. Personally I'd like it to be part of the regular install
>>>>>     guide, but if you have another idea please share it.
>>>>>
>>>>>
>>>>> Something I'd like to see implemented with a spec for doc tooling is
>>>>> this:
>>>>> 1. Author install guide articles in your doc/source directory.
>>>>> 2. Create a common TOC to pull many install guide articles together to
>>>>> build an install guide that goes beyond defcore projects to
>>>>> docs.openstack.org/ <http://docs.openstack.org/><relname>/<distro>/
>>>>> 3. Serve multiple users needs by building on existing install guide in
>>>>> a
>>>>> modular way without burdening the center.
>>>>>
>>>>> Do you have anyone who might want to take that idea on?
>>>>>
>>>>
>>>> I like the above idea, but I would prefer to keep the actual source for
>>>> the install guides in a centralized tree. We could call it the "extended
>>>> install guide" or "install guide appendix" -- I don't really care. The
>>>> point is to follow the same model we've been following with other guides
>>>> and to do things similarly to how the existing install guide is done to
>>>> facilitate an eventual merge (if the docs team decides to go that way).
>>>>
>>>
>>> I'm not sure what the gain is for moving the source to a centralized
>>> tree. I think that the gain for keeping source where experts can review and
>>> test is the better path to high-quality content.
>>>
>>> To me, there are a few resource limiters:
>>>
>>> 1. Packagers and packages for the distros we currently support: RHEL,
>>> Centos, OpenSUSE, SUSE Linux Enterprise Server, Ubuntu, and Debian.
>>> 2. Testers for the install instructions using packages and also
>>> integration with the "core" architecture.
>>> 3. Reviewers for the install content itself across all the distros who
>>> know manilla well.
>>>
>>> How are you doing as far as coverage on the first two resources?
>>>
>>> Anne
>>>
>>>
>>>>
>>>> -Ben
>>>>
>>>> Thanks,
>>>>> Anne
>>>>>
>>>>>
>>>>>     -Ben Swartzlander
>>>>>     Manila PTL
>>>>>
>>>>>     [1] https://review.openstack.org/#/c/213756/
>>>>>     [2]
>>>>> http://www.openstack.org/software/releases/liberty/components/manila
>>>>>
>>>>>     _______________________________________________
>>>>>     OpenStack-docs mailing list
>>>>>     OpenStack-docs at lists.openstack.org
>>>>>     <mailto:OpenStack-docs at lists.openstack.org>
>>>>>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Anne Gentle
>>>>> Rackspace
>>>>> Principal Engineer
>>>>> www.justwriteclick.com <http://www.justwriteclick.com>
>>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> OpenStack-docs mailing list
>>>> OpenStack-docs at lists.openstack.org
>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>>>
>>>
>>>
>>>
>>> --
>>> Anne Gentle
>>> Rackspace
>>> Principal Engineer
>>> www.justwriteclick.com
>>>
>>> _______________________________________________
>>> OpenStack-docs mailing list
>>> OpenStack-docs at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>>
>>>
>>
>
>
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20151208/b3a08cf2/attachment-0001.html>