Open Stack

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 09/12/15 05:32, Ben Swartzlander wrote:
> On 12/08/2015 02:13 AM, Lana Brindley wrote:
> 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.

The Install Guide is the only book that is thoroughly tested against new packages before each release. Every other book (with one minor exception of the config ref, but it's another special case) is continuously updated and no other book has content that is tested in any formal sense. The Install Guide is a little special for this reason alone. You might have noticed with the Liberty release that we didn't immediately publish the Red Hat or Debian versions of the guide. That was because we had some packaging issues and were unable to test it to our satisfaction. In fact, while the Red Hat version has now been tested and published, we are still working on Debian. No other book goes through this level of testing rigour. Because testing documentation is fairly thankless work, with not even any gerrit stats to show for the effort, we are naturally quite hesitant to increase the amount of work our testers take on, and the main reason why we limited the scope of the Install Guide a few rele
ases ago.

The Install Guide is, more than any other book, designed to be a learning tool. Very few people would, once they understand OpenStack, be willing to install and run OpenStack using the method in the Install Guide. The book is primarily for people new to OpenStack to get the main pieces up and running in a manual way, to help them understand each piece and the way it should and can be configured. In fact, we expressly state this in the guide and point out that it is not in the least suitable for a production environment.

I'm happy to consider a second, supplementary Install Guide for other components (and this is something the docs team have discussed in the past as a distinct possibility) that does not have the same review rigour, in conjunction with the Install Guide speciality team and what they feel is feasible. The existing Install Guide serves a very distinct purpose, though, and I'm unwilling at this stage to consider extending it.


> 
>>>>>      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?

These issues do exist for the other guides, but in a less specific way because they don't undergo the testing that the Install Guide does. With the Config Ref especially, we do just expect projects to maintain their own portions of the content, and that tends to work relatively well. Because  we don't edit those books so closely, release them updated packages for each version, or thoroughly test them, that overhead is much lower, and the burden on project teams (and the appropriate documentation speciality teams) is much lower.

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/

iQEcBAEBCAAGBQJWZ1MyAAoJELppzVb4+KUyyaQIAJ07teJRt3wxBgJt4PuJm5qx
5WtpuaI3otsLQp31ww3uyAeb0J1PiEx76dOgx/iQBIUJiC/foLcLxNTV4WPH1Le3
WxGwcQv1CeGy0JUI3ErpYaOPaiKVYmcMXdM9EmVpkuuvXlaetjjSXf546Pyw6Nm2
h3rJcJEXlQORFP4270VxWqKOGsQNP88Zq7MPipGcoSElMRQ34bCVFM8yawij1pVP
HEeOVjr84NJUrCpTL28bIu7ePc02tl9QIE9NSw2beWnvxjHqdm1Y2cTOs8spyoqE
72wMkyC9bMy1+pJ5+ghkNnyOP0E3T3/gEcsaZASsm+0BT8kHzcFDnPnHVYDLlCY=
=0T02
-----END PGP SIGNATURE-----