Open Stack

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

On 08/03/16 02:09, Hayes, Graham wrote:
> On 07/03/2016 16:00, Matt Kassawara wrote:
>> Snipping a lot, because I'm particularly interested in one comment...
>>
>>
>>     I agree that many developers (especially developers of those groups
>>     new to the big tent) seem to think that they need to be on the top
>>     level docs.openstack.org <http://docs.openstack.org>, without
>>     necessarily understanding that docs.openstack.org/developer
>>     <http://docs.openstack.org/developer> is usually the more
>>     appropriate place, at  least to begin with. This should probably be
>>     made more explicit both in the Infra Manual, plus anywhere that
>>     Foundation is discussing big tent inclusion.
>>
>>
>> We tell operators and users to look at the documentation on
>> docs.openstack.org <http://docs.openstack.org> because the documentation
>> in /developer is aimed at developers and often lacks polish. Now we're
>> telling developers to put operator/user documentation into /developer?
> 
> To follow up on that - the Foundations "Project Navigator" has one of
> the maturity requirements as "Is there an install guide for this
> project guide (at docs.openstack.org)?"
> 
> If this is required, how can projects get content in to this.
> 
> I went looking about 6 months ago for the information that Stephen
> asked for to update (create) our docs, but couldn't find it.
> 

To try and answer both questions in one reply: The developer documentation should live on /developer, with config options automatically picked up for the Config Reference where appropriate. If you are new to the big tent, then you should also use /developer to create and polish your user documentation. This is enough to be considered 'official' according to the Project Navigator. Once you have a good amount of quality content, then please feel free to open a conversation with docs about inclusion in the top level.

The main reason we do it this way is because writing docs is a very manual, labour-intensive task, and the docs team is small. We already have a lot of content that we maintain and a lot of people throwing things over the wall to us. We simply cannot have every big tent project present in the Install Guide.

Hope that helps clear things up.

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/

iQEcBAEBCAAGBQJW3gf/AAoJELppzVb4+KUygvgH/3CLosJOZQ4HOGzZ6gyESAip
7gxKSNRaN9LTVXGUFMpSwppDMPguM2X78bpQB1cSa6A20mvRHbHKVFtio/virn1l
05R0iWRR5I157ggfVFA8P+tLeVONVTQi0Sa9W/L6GU/Ihr7mplVptYz5tpipmJy9
RYwa3LlOCF1qMQogOdNcv+5Tg2ci6Sqn03xw43jN18iC2dAtJVZJxmjO760mJ9h9
9uLDpb8GOvrCNvM4hdiWoZlEIbYpViaZGcYqQElml1RqZOmzswC1GOrquGIENkTl
eClj7UFUUji0/6WqeoDjSq/60NzT/i+IYvBd0bFDPgmn2kZLt67xCgoyfrj1Cik=
=AfBL
-----END PGP SIGNATURE-----