Open Stack

On 11.07.2016 00:02, Steve Martinelli wrote:
> I personally like this solution, it seems much more scalable. This follows
> the same pattern of the API docs (moving the content to project repos),
> which puts the onus back on the project team to maintain and create
> documentation. I'm also hoping this results in less duplication between the
> guides and the keystone developer docs (the latter of which start to stray
> from "developer" docs and begin to look like "user" docs.

After reading this, the "configuration reference" comes to my mind.
Having the api-ref and the config-ref at one place, near the code, seems
logical to me. Nova put a lot of effort into providing valuable help
text for the config options in the last months. We should also make sure
that it will result in a good manual, which could be easier if it's
in-tree, near the code.

-- 
Regards, Markus Zoeller (markus_z)

> The folks that contribute to the keystone guides today would still be very
> welcomed to continue to contribute once/if the switch is made.
> 
> On Fri, Jul 8, 2016 at 5:02 PM, Matt Kassawara <mkassawara at gmail.com> wrote:
> 
>> Currently, OpenStack provides central documentation (primarily in the
>> openstack-manuals repository) for operators and users. The single location
>> and consistent structure eases audiences of various technical expertise
>> into OpenStack, typically operators and users rather than developers.
>> Although I'm not a fan of the word "product", increasingly less technical
>> audiences are learning about OpenStack and tend to compare it with other
>> cloud infrastructure products. Such audiences expect a coherent, relatively
>> mature product to easily evaluate, usually via proof-of-concept. Upon
>> deciding to implement OpenStack, the central documentation attempts to
>> gracefully lead them toward a production deployment that meets or exceeds
>> requirements and expectations.
>>
>> However, since I began contributing to OpenStack documentation around the
>> Havana release, I am seeing many projects, particularly core projects,
>> trending toward more independence from other projects including central
>> documentation. For operator and user documentation, a couple of projects
>> contribute to the central documentation repository, some projects
>> contribute to their own repositories, and an alarmingly large number of
>> projects simply do not contribute such documentation and assume that all
>> audiences involve developers. These differences lead to an increasingly
>> negative overall experience for the audiences that OpenStack needs to
>> increase adoption/growth and maintain the existing deployment base.
>>
>> As a contributor to central documentation and one or more other projects
>> including neutron, I see the problems from both sides and don't
>> particularly blame either party for them. Some politics, some technical,
>> some a lack of resources, and some just a general misunderstanding about
>> documentation. However, I think we need to develop a solution that works
>> for both parties and ultimately benefits our audiences.
>>
>> One potential solution essentially involves moving operator and user
>> documentation into project repositories (similar to developer
>> documentation) and using infrastructure to coherently present it on
>> docs.openstack.org which achieves the following goals:
>>
>> 1) Project developers can contribute documentation and code in the same
>> patch, thus avoiding two different review queues and reviewers with
>> different motivations and guidelines.
>> 2) Project developers can either work directly or via liaison with one or
>> more documentation team members to improve documentation components during
>> development or after merging technically accurate content.
>> 3) Rather than attempting to document all projects with little (if any)
>> assistance from those projects, the primary role of the documentation team
>> becomes managing overall organization/presentation of documentation and
>> assisting projects with their contributions.
>>
>> We're seeing decent adoption of moving API documentation into project
>> repositories, so I want to initiate some discussion about moving additional
>> documentation (or other options) prior to mid-cycles (including ops) and
>> the next summit.
>>
>> Matt
>>
>> __________________________________________________________________________
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>>
> 
> 
> 
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>