Open Stack

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.

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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160710/cf97e6c8/attachment.html>