[openstack-dev] The future of OpenStack documentation

Matt Kassawara mkassawara at gmail.com
Mon Jul 11 23:45:56 UTC 2016


Inline...

On Sun, Jul 10, 2016 at 5:22 PM, Lana Brindley <openstack at lanabrindley.com>
wrote:

> On 09/07/16 07:02, Matt Kassawara 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.
>
> bI know the UX team have been working on getting some data around this,
> but I'd be interested to know what data you have. The User Survey
> highlighted that, while OpenStack itself is difficult to understand, most
> people are pretty happy with the current state of the documentation. Also,
> of the core projects that users interact with, we have a good relationship
> with the Cross Project Liaisons and PTLs, and are consistently working with
> them to keep docs up to date. Docs are very much a living thing, especially
> in a situation like ours, where there are a lot of components all at
> different maturity levels. Is there something specific you feel we're
> dropping a ball on?
>

Most of my data involves a combination of observations from providing
support in #openstack (and some other channels) on IRC, mailing list posts,
bug reports, and attempting to use (or reference) the existing
documentation.


>
> >
> > 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.
>
> I don't think I fully understand the problem you're trying to solve here,
> yet, which makes it difficult to determine a solution.
>

I'm trying to solve the problem of the central documentation content
falling behind the development curve of OpenStack. The documentation team
can't keep up with the exponential growth of OpenStack and most projects
don't contribute sufficient documentation for the audiences that the
central documentation serves. The user guide came to mind today when I
attempted to link to it for OpenStack client commands and found out it
doesn't even mention the OSC. How do we get users to adopt the OSC if the
documentation doesn't cover it?


>
> >
> > 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 <http://docs.openstack.org/> which achieves the
> following goals:
>
> But I still don't understand what problem you're solving for here. Is the
> problem that developers aren't contributing to docs? That the docs are out
> of date? That users aren't finding the right docs?
>

All of the above.


>
> >
> > 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 did something very similar with the Install Guide because it was the
> most efficient way to allow all big tent project teams to have an Install
> Guide on docs.o.o, while still providing a central point for users to go to
> find the content. I'm happy to consider doing this for other projects, but
> we need to wait until the new Install Guide is live for Newton, and we have
> some solid feedback on whether or not the project was a success. Right now,
> we're still implementing it.
>

As much as I want to include big tent projects in the installation guide,
attempting to combine distribution packages and source installations
without carefully solving the potential problems prior to incorporating
external (in-tree) content will degrade or break the most important
documentation for the adoption of OpenStack.


>
> > 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.
>
> We will definitely be doing a full retro on the Install Guide project in
> Barcelona, but getting user data will take longer, so I expect that before
> Sydney.
>
> L
>
> --
> Lana Brindley
> Technical Writer
> Rackspace Cloud Builders Australia
> http://lanabrindley.com
>
>
> __________________________________________________________________________
> 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/20160711/1e3f2fc4/attachment.html>


More information about the OpenStack-dev mailing list