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 <[email protected]> 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. <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 >>>> [email protected] >>>> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer >>>> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer >>> >>> _______________________________________________ >>> QGIS-Developer mailing list >>> [email protected] >>> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer >>> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer >> >> _______________________________________________ >> QGIS-Developer mailing list >> [email protected] >> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer >> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer > > _______________________________________________ > QGIS-Developer mailing list > [email protected] > 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 _______________________________________________ QGIS-Developer mailing list [email protected] List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
