<div dir="ltr">Inline...<br><div class="gmail_extra"><br><div class="gmail_quote">On Sun, Jul 10, 2016 at 5:22 PM, Lana Brindley <span dir="ltr"><<a href="mailto:openstack@lanabrindley.com" target="_blank">openstack@lanabrindley.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 09/07/16 07:02, Matt Kassawara wrote:<br>
> 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.<br>
><br>
> 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.<br>
<br>
</span>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?<br></blockquote><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class=""><br>
><br>
> 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.<br>
<br>
</span>I don't think I fully understand the problem you're trying to solve here, yet, which makes it difficult to determine a solution.<br></blockquote><div><br></div><div>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?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
><br>
> 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 <a href="http://docs.openstack.org" rel="noreferrer" target="_blank">docs.openstack.org</a> <<a href="http://docs.openstack.org/" rel="noreferrer" target="_blank">http://docs.openstack.org/</a>> which achieves the following goals:<br>
<br>
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?<br></blockquote><div><br></div><div>All of the above.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class=""><br>
><br>
> 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.<br>
> 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.<br>
> 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.<br>
><br>
<br>
</span>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.<br></blockquote><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class=""><br>
> 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.<br>
<br>
</span>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.<br>
<span class="HOEnZb"><font color="#888888"><br>
L<br>
<br>
--<br>
Lana Brindley<br>
Technical Writer<br>
Rackspace Cloud Builders Australia<br>
<a href="http://lanabrindley.com" rel="noreferrer" target="_blank">http://lanabrindley.com</a><br>
<br>
</font></span><br>__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div></div>