On 11.07.2016 00:02, Steve Martinelli wrote: > I personally like this solution, it seems much more scalable. This follows > the same pattern of the API docs (moving the content to project repos), > which puts the onus back on the project team to maintain and create > documentation. I'm also hoping this results in less duplication between the > guides and the keystone developer docs (the latter of which start to stray > from "developer" docs and begin to look like "user" docs.
After reading this, the "configuration reference" comes to my mind. Having the api-ref and the config-ref at one place, near the code, seems logical to me. Nova put a lot of effort into providing valuable help text for the config options in the last months. We should also make sure that it will result in a good manual, which could be easier if it's in-tree, near the code. -- Regards, Markus Zoeller (markus_z) > The folks that contribute to the keystone guides today would still be very > welcomed to continue to contribute once/if the switch is made. > > On Fri, Jul 8, 2016 at 5:02 PM, Matt Kassawara <mkassaw...@gmail.com> 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. >> >> 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. >> >> 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 which achieves the following goals: >> >> 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'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. >> >> Matt >> >> __________________________________________________________________________ >> OpenStack Development Mailing List (not for usage questions) >> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> >> > > > > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
