Open Stack

On 09/05/16 22:57, 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?

I have mixed feelings about this.  I have contributed documentation in
the past, and felt frustrated by the level of pickiness of the reviews -
to the extent of being somewhat demotivated about contributing more doc
improvements and additions.  So I think I understand where this
conversation is arising from.

On the other hand, firstly I like some of the pickiness, e.g. I don't
really want to see our docs littered with spelling mistakes - so it
might just be that I'm being subjective about what I think is good and
bad pickiness; and secondly I think we should acknowledge that this
isn't only a documentation issue: I've had 'could you also clean this up
while you're in the area' comments, and comments that seem to ask for
things just because they can, rather than being properly argued or
clearly beneficial, for code changes just as much as for docs.

On balance, though, and given that IMO we are still lacking a lot of
important OpenStack documentation (or documentation structure), I think
it would be good for documentation reviewers to adjust their bar down
slightly, so as to encourage more contributions.

I'm not sure if that needs the detailed solution proposed above; it
should be enough for the team to agree an adjusted approach among
themselves.

Regards,
    Neil