[QGIS-Developer] Require documentation PR for new features

[Alexis R.L.]

Greetings,

Matthias there is one point that you raised that should be a non-issue. The
barrier of entry aspect, I think this is false.

Non-core contributor often need to write more documentation to showcase the
use of their work and its behaviour. In some way documenting properly
things is more of an obligation than a barrier of entry.

The only point that concerns me is that PR documentation is meant to be on
its own, this is fine for detailed changelog, but integrating this properly
to the documentation is a whole new thing.

This is why I think using PR header/posts is good to populate the changelog
when sufficiently detailed, but doing the integration part seems more
complex and may demand more time to update the figures and format things
properly.

Thanks and have a nice day,

Alex


Le jeu. 15 avr. 2021 à 13:49, Matthias Kuhn <matthias at opengis.ch> a écrit :

> Hi
>
> Thanks for raising this topic Alessandro. I agree we need better
> documentation.
>
> Some questions:
>
> What do we do with interesting feature pull requests and no documentation?
> Stale away?
> Who decides if the quality of the documentation is good enough?
> Who decides if documentation is required?
> Will the review job (in the QGIS repository itself) be required to look up
> if the attached documentation has been approved before being allowed to hit
> the merge button?
> Is there enough guidance around about where exactly in the doc repository
> this should end up?
> Did we fail to encourage people to write good enough docs in the pull
> request message so far or did we fail to copy good documentation from the
> pr comment into the docs?
>
> I am torn between an apparent easy win for better docs at first sight and
> a better handle on clients to sponsor docs, a better handle on devs to
> write docs and an increased entry barrier to participate and continue
> contributing and the review process.
>
> Matthias
>
> On Thu, Apr 15, 2021 at 7:21 PM Jürgen E. Fischer <jef at norbit.de> wrote:
>
>> Hi,
>>
>> On Thu, 15. Apr 2021 at 14:15:16 +0200, Alessandro Pasotti wrote:
>> > - 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
>>
>> > Any opinion?
>>
>> I'd say requiring volunteers to do anything they didn't volunteer for is
>> unfair.
>>
>> Giving people who volunteered to write documentation new stuff to write
>> about
>> doesn't fall into that category.
>>
>> But requiring people who volunteered to write features to write
>> documentation
>> OTOH does.
>>
>> And as you said not all authors are paid for the feature.  But probably
>> less
>> than there used to be as more and more hoops like this one make even
>> little
>> contribution a big effort.
>>
>>
>> Jürgen
>>
>> --
>> Jürgen E. Fischer           norBIT GmbH             Tel.
>> +49-4931-918175-31
>> Dipl.-Inf. (FH)             Rheinstraße 13          Fax.
>> +49-4931-918175-50
>> Software Engineer           D-26506 Norden
>> https://www.norbit.de
>>                             Germany                    IRC: jef on
>> FreeNode
>> _______________________________________________
>> 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
>>
> _______________________________________________
> 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/20210415/a64adaa6/attachment.html>