Open Stack

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?

> 
> 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.

> 
> 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?

> 
> 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.

> 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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 538 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160711/c9ba62de/attachment.pgp>