[openstack-dev] The future of OpenStack documentation

Matt Kassawara mkassawara at gmail.com
Fri Jul 8 21:02:01 UTC 2016

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.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160708/5b09da3d/attachment.html>

More information about the OpenStack-dev mailing list