[QGIS-Developer] Require documentation PR for new features

[Alessandro Pasotti]

Thank you all for the feedback.

I'll try to make a QEP with a revised proposal and see if we can come
up with a solution that makes everyone happy.




On Fri, Apr 16, 2021 at 8:37 AM Peter Petrik
<peter.petrik at lutraconsulting.co.uk> wrote:
>
> Hi,
>
> a good software developer doesn't need to be a good or even acceptable documentation writer. It is a completely different set of skills IMHO, starting with the language skills, ending with the  different point of view to the problem (we developers tend to looks at the algorithm selection, code quality, performance, ... where in docs you want to look at it from user point of view, without burden of C++ code details) . Not talking about the knowledge of all other parts of documentation, so the new piece fits to the overall "style" and adds the value.
>
> I would prefer to require a very good PR description that can be easily translated to docs/changelog by the documentation team. Of course when the feature is part of a paid contract, it would be more good if documentation is agreed beforehand and budgeted in the contract.
>
> Cheers,
> Peter
>
>
>
> On Thu, Apr 15, 2021 at 10:42 PM Alexis R.L. <alroyliz0 at gmail.com> wrote:
>>
>> 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
>>
>> _______________________________________________
>> 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



-- 
Alessandro Pasotti
QCooperative:  www.qcooperative.net
ItOpen:   www.itopen.it