[QGIS-Developer] Require documentation PR for new features

[Paolo Cavallini]

+1 for me
thanks Ale for raising this

Il 15/04/21 14:15, Alessandro Pasotti ha scritto:
> 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?
> 

-- 
Paolo Cavallini
www.faunalia.eu - QGIS.org
training, support, development on QGIS, PostGIS and more