Open Stack

-----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'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.

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