Open Stack

On 12/07/16 09:45, Matt Kassawara wrote:
> Inline...
> 
> On Sun, Jul 10, 2016 at 5:22 PM, Lana Brindley <openstack at lanabrindley.com <mailto: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.
>  
> 

I think is falling into the 'gut feel' region as far as data goes. As I said, we're working on a research project to gather actual data about this, so I'd like to base decisions on that more than on a small sample size.

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

Documentation falling behind development on a project such as this is not terribly surprising, or unexpected. As you know, we've changed the Install guide project to try and address the big tent growth issue, but we really need to sit back and wait until that's been implemented before we can bubble those changes out to the rest of the docs project.

I know this is a favourite bugbear of yours, and for the record I agree with you, but we also need to be realistic about what we can achieve. We've already achieved a large amount of positive progress in this direction during the Newton release, and I'm sure we'll continue to innovate and expand over future releases. As you correctly point out, the documentation team is small, and there's only so much we can achieve every release.

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

It's an iterative process. The Install Guide (as you well know) was the thing we got yelled at over the most, so that's naturally where we focused. I agree that starting with the biggest and most complicated project is not always the best idea, but I guess that's just a case of the squeaky wheel getting the grease. However, your comments here are exactly why I want to bed down the Install Guide changes before making changes across the board. I certainly think your idea has merit, and I would like to work towards a similar solution. I just can't make it happen overnight. 

> 
>     > 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/20160713/d60ebe46/attachment.pgp>