On 10/05/16 20:08, Julien Danjou wrote: > On Mon, May 09 2016, Matt Kassawara wrote: > >> So, before developer frustrations drive some or all projects to move >> their documentation in-tree which which negatively impacts the goal of >> presenting a coherent product, I suggest establishing an agreement >> between developers and the documentation team regarding the review >> process. > > My 2c, but it's said all over the place that OpenStack is not a product, > but a framework. So perhaps the goal you're pursuing is not working > because it's not accessible by design? > >> 1) The documentation team should review the patch for compliance with >> conventions (proper structure, format, grammar, spelling, etc.) and provide >> feedback to the developer who updates the patch. >> 2) The documentation team should modify the patch to make it compliant and >> ask the developer for a final review to prior to merging it. >> 3) The documentation team should only modify the patch to make it build (if >> necessary) and quickly merge it with a documentation bug to resolve any >> compliance problems in a future patch by the documentation team. >> >> What do you think? > > We, Telemetry, are moving our documentation in-tree and are applying a > policy of "no doc, no merge" (same policy we had for unit tests).
This is great news! I love hearing stories like this from project teams who recognise the important of documentation. Hopefully the new model for Install Guides will help you out here, too. > So until the doc team starts to help projects with that (proof-reading, > pointing out missing doc update in patches, etc) and trying to be part > of actual OpenStack projects, I don't think your goal will ever work. > > For example, we have an up-to-date documentation in Gnocchi since the > beginning, that covers the whole project. It's probably not coherent > with the rest of OpenStack in wording etc, but we'd be delighted to have > some folks of the doc team help us with that. Let's work together to find out how we can help. I note that Lance Bragstad is your CPL, is that still current? Lana -- Lana Brindley Technical Writer Rackspace Cloud Builders Australia http://lanabrindley.com
signature.asc
Description: OpenPGP digital signature
__________________________________________________________________________ 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
