On 10/05/16 07:40, Matt Kassawara wrote: > At each summit, I speak with a variety of developers from different projects > about the apparent lack of contributions to the central documentation. At > previous summits, the most common complaint involved using DocBook. After > converting most of the documentation to RST, the most common complaint at the > recent summit involves the review process, particularly the lengthy amount of > time patches sit in the review queue with -1s for various "conventions" > problems such as structure, formatting, grammar, spelling, etc. Unlike most > OpenStack developers that focus on a particular project, the documentation > team covers all projects and lacks the capacity to understand each one enough > to contribute and maintain technically accurate documentation in a timely > manner. However, covering all projects enables the documentation team to > organize and present the documentation to various audiences, primarily > operators and users, that consume OpenStack as a coherent product. In other > words, the > entire process relies on developers contributing to the central > documentation. 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. > > As much as the documentation team wants to present OpenStack as a coherent > product, it contains many projects with different contribution processes. In > some cases, individual developers prefer to contribute in unique ways. Thus, > the conventional "one-size-fits-all" approach that the documentation team > historically takes with reviewing contributions from developers yields > various levels of frustration among projects and developers. I ran a > potential solution by various developers during the recent summit and > received enough positive feedback to discuss it with a larger audience. So, > here goes... > > A project or individual developer decides the level of documentation team > involvement with reviewing patches. The developer adds a WIP to the > documentation patch while adding content to prevent premature reviews by the > documentation team. Once the content achieves a sufficient level of technical > accuracy, the developer removes the WIP and adds a comment in the review > indicating of the following preferences: > > 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? > >
This is a really important discussion, so thank you for raising it, Matt. First of all, I want to point out that there are no hard and fast rules for how developers can or should contribute to documentation. In my opinion, nor should there be. As Matt so rightfully points out: "individual developers prefer to contribute in unique ways". With that in mind, I think we need to make sure that developers feel they can contribute any type of documentation that they feel improves the existing docs set, and if they need help with improving their writing skills, or would like to invite a writer to take their content and improve the writing in a new patchset, all they need to do is ask in the comments, or reach out on the mailing list. I've worked with many developers over many years to take their rough working notes and turn it into well written content, and I have no doubt that we can continue to do so into the future. All that said, I would like the documentation team (cc'd here) to consider an update to our Contributor Guide (http://docs.openstack.org/contributor-guide/index.html) that more explicitly outlines our review policy, especially in regard to editing contributions from those outside the usual documentation team, and to more accurately apply the "is it better than what we already have" rule on reviews. Writers, I have to admit, are very prone to getting to a little pedantic from time to time, so it's good to remind ourselves that we don't always need to do that thing. Again, thanks for bringing this up, and I hope that it helps to communicate that it doesn't matter how good your written English is, if you feel you have something to add to the documentation, the docs team are here to help you, not mark you down and send you off to the principal for a detention ;) L -- 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
