Open Stack

On 12/08/2015 02:13 AM, Lana Brindley wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> On 08/12/15 05:44, Ben Swartzlander 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.
>
> If your main concern is increasing the maturity of the project, then publishing an Install Guide in your own source is certainly the easiest and most effective way to make that happen.
>
> Are you able to elaborate on your reticence to use this as a solution?

I guess I'm a bit confused by the special treatment for the install 
guide. For the security guide, operations guide, config guide, admin 
guide, API guide, and high availability guide, the effort seems to be to 
pull the information for all projects into a central place. Manila has 
updated all of those guides with Manila-related information so we don't 
need to keep that information in our own repo.

The install guide is the only guide I'm aware of where there seems to be 
an aversion to centralizing the information in one place. Maybe the 
other guides will follow the path of the install guide and throw all the 
Manila stuff out (encouraging us to put it back in our own tree) but I 
hope that doesn't happen.

Regarding the issue of maintenance burden, I expect that the Manila team 
will continue to be responsible for fixing bugs in Manila-related docs 
even though we've moved the content into the manuals project. I don't 
see why that can't also be true for the install guide.

Is there something special about the Install guide that makes it 
extra-burdensome to centralize? If there's a good reason then I'm more 
than happy to follow the recommended course of action and put our 
install guide somewhere else. Right now it just feels arbitrary that the 
install guide is run differently from the rest of the manuals.

>>>      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).
>
> To be honest, the main point of trimming the install guide to defcore components was to reduce the maintenance and testing overhead. If we maintained Install Guide content for every project in our repo to the same standard, but called it something different, it doesn't solve that problem. What Anne's solution aims to do is shift the maintenance and testing burden back to the developer teams, which is a much more sustainable way of doing it. Expecting the docs team to write, maintain, test, and publish Install Guide content for 40 or more projects is a little harsh, when we often struggle to get the six projects we *do* cover complete every release.

This partially answers my question, but it doesn't explain why the same 
logic doesn't apply to the rest of the manuals. Why don't the same 
issues (testing, publishing, maintaining, etc) exist for, say, the API 
reference, or the config guide?

-Ben

> 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/
>
> iQEcBAEBCAAGBQJWZoMPAAoJELppzVb4+KUyurwIAKF1v9NFGV/5IPnaJDO4HBPN
> 5dHhwCN6XvS/qo/rKkrwbipd0IHoxKgdLS3bnwqDO1S+W1BFx8YHwanfkUzNcGbd
> sjjMFts6B+zV0hw4Lj494u6vdDQQWODRCwjqP7XX6jjTbM9efdBkLxRluv8atz5C
> NLVUAD7iWRoR/7Aqo1DRlTonpKBivEoS1wHREwGitU3domBqm7wWS7w0PrRdzYqa
> Ed5qffm/e4z+UxVEEt+PikcXYN0ShjHNaE6W6MtWUn+QdCV9Xy6xMP3ELVi5khCD
> +M3VM7mUvQjqWkNFSlXWxY80ebE916cVm3QrPfrxJFpi2M/8Kf9ZH+uFMnsXH3M=
> =SOkk
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>