<div dir="ltr"><div style="font-size:12.8px"><span style="font-size:12.8px">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.</span><br></div><div style="font-size:12.8px"><br></div><div style="font-size:12.8px">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.</div><div style="font-size:12.8px"><br></div><div style="font-size:12.8px">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></div><div style="font-size:12.8px"><br></div><div style="font-size:12.8px">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/" target="_blank">docs.openstack.org</a> which achieves the following goals:</div><div style="font-size:12.8px"><br></div><div style="font-size:12.8px">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.</div><div style="font-size:12.8px">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.</div><div style="font-size:12.8px">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.</div><div style="font-size:12.8px"><br></div><div style="font-size:12.8px">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.</div><div><br></div><div>Matt</div></div>