Open Stack

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20151208/91366349/attachment.html>