Loomio
Sun 7 Jan 2018 8:37PM

Mandating documentation to accompany feature pull requests

TS 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.

TS

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 JEF MK MD DR AB ND AN MP AP
Yes I agree to this proposal. 35.7% 5 PC S TK PB HM
Undecided 0% 13 TS GS WM NW LS SL DU M PK SB RB SM V

14 of 27 people have participated (51%)

JEF

Jürgen E. Fischer Mon 8 Jan 2018 7:32AM

No I don't agree to this proposal.

s/Require/Encourage/

MP

Mathieu Pellerin Mon 8 Jan 2018 8:28AM

No I don't agree to this proposal.

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

MK

Matthias Kuhn Mon 8 Jan 2018 10:18AM

No I don't agree to this proposal.

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.

MK

Matthias Kuhn Mon 8 Jan 2018 10:19AM

No I don't agree to this proposal.

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.

AP

Alessandro Pasotti Mon 8 Jan 2018 11:17AM

No I don't agree to this proposal.

As stated in my comment, I'd agree if reworded.

AN

Andreas Neumann Mon 8 Jan 2018 12:59PM

No I don't agree to this proposal.

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.

ND

Nyall Dawson Mon 8 Jan 2018 1:06PM

No I don't agree to this proposal.

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

MD

Martin Dobias Tue 9 Jan 2018 8:59AM

No I don't agree to this proposal.

Same concerns as raised already by others

ND

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?

Load More