Open Stack

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 538 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160510/c1934675/attachment.pgp>