[QGIS-Developer] Require documentation PR for new features

[Peter Petrik]

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20210416/c59c0c38/attachment.html>