[QGIS-Developer] Require documentation PR for new features

[Nyall Dawson]

On Thu, 15 Apr 2021 at 10:15 pm, Alessandro Pasotti <apasotti at gmail.com>
wrote:

> Hi,
>
> I think it would be wise to add a new policy about documentation for
> new features which requires a parallel Documentation PR to be opened
> and approved before we accept and merge new features into master.
>
> This is a common policy for other open source projects: documentation
> is a first class citizen of the software ecosystem and shouldn't be
> left behind.
>
> I don't need to stress out how important it is to have high quality
> documentation.
>
> Uptil now we have required the authors to provide enough information
> for others to write the documentation introducing an unnecessary
> burden over the shoulders of the few volunteers that are currently
> maintaining the documentation.
>
> There are good reasons to ask authors to also take care of the
> documentation of the feature they write:
>
> - authors know all the details of the new feature and how and where it
> has an impact on UX and user workflows
> - most of the times authors have been paid for the new feature and it
> doesn't look fair to me that the documentation is left to volunteers
> - while developing and testing the new feature it is easy for authors
> to produce snapshots and notes that can be used directly for the
> documentation, it is harder for others
> - if the documentation lags behind it is difficult for testers and
> users to determine how the new feature should behave and if an
> apparent anomaly is a bug or not
>
> Any opinion?


In the past when this idea was raised the documentation team themselves
were against it. That may have changed, but we should wait for comment from
them as to whether this is now a desirable approach.

(If I recall correctly the rationale was that a well written pr message led
to less work for the team vs them mentoring badly written documentation prs
through to completion.)

Nyall


>
> --
> Alessandro Pasotti
> QCooperative:  www.qcooperative.net
> ItOpen:   www.itopen.it
> _______________________________________________
> QGIS-Developer mailing list
> QGIS-Developer at lists.osgeo.org
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20210416/500e0492/attachment.html>