Mandating documentation to accompany feature pull requests
Tim Sutton
Public
Seen by 24
Dear QGIS developers. At our last PSC meeting, there was a proposal that we should mandate that any new features being added to QGIS be accompanied by user documentation. This would be much like requiring that core library changes are accompanied by tests.
Our rationale for this proposal is that the documentation has a really hard time keeping up with the new features that are being added. Also often new features are quite technical and difficult to document. Lastly, we thought it makes sense to pass on the responsibility of having well-documented features to those that fund new feature development - your clients and benefactors. Feel free to discuss your thoughts on this in this thread and cast your vote on the accompanying proposal.
Poll Created Sun 7 Jan 2018 8:40PM
Motion: Require that feature PR's are accompanied by documentation Closed Sun 14 Jan 2018 8:41PM
Results
| Results | Option | % of points | Voters | |||
|---|---|---|---|---|---|---|
|
|
No I don't agree to this proposal. | 64.3% | 9 |
|
||
|
|
Yes I agree to this proposal. | 35.7% | 5 |
|
||
| Undecided | 0% | 13 |
|
14 of 27 people have participated (51%)
Mathieu Pellerin Mon 8 Jan 2018 8:28AM
I'm inclined to disagree with this proposal:
- overly burdensome for non English native speakers
- a missed opportunity to get non-dev community members to get involved in project
- documenting a feature acts as a review by a 3rd party, useful/needed
Matthias Kuhn Mon 8 Jan 2018 10:18AM
I agree that the required information should be made available by the developer. I disagree that this should be done as documentation itself, the reasons have been outlined very well by Alessandro and Mathieu.
Matthias Kuhn Mon 8 Jan 2018 10:19AM
I agree that the required information should be made available by the developer. I disagree that this should be done as documentation itself, the reasons have been outlined very well by Alessandro, Alexander and Mathieu.
Alessandro Pasotti Mon 8 Jan 2018 11:17AM
As stated in my comment, I'd agree if reworded.
Andreas Neumann Mon 8 Jan 2018 12:59PM
It concentrates more work on core devs who are already busy. Documentation is a possible work for people who want to contribute but don't want to code. I agree though that devs should provide sufficient information for documenters to write docs.
Nyall Dawson Mon 8 Jan 2018 1:06PM
I'd be in favour of mandating detailed commit messages which describe a feature in depth to assist the documenters, but we should do that anyway. Also disagree that devs provide screenshots, as it results in inconsistent look and branding in the docs
Martin Dobias Tue 9 Jan 2018 8:59AM
Same concerns as raised already by others
Nyall Dawson · Sun 7 Jan 2018 8:55PM
I recall bringing up this idea in the past, but the documentation team at the time stating that detailed commit messages are sufficient and they were not in favour of the idea. Has that position changed? Does the documentation team now favour this approach?