Loomio

Mandating documentation to accompany feature pull requests

Tim Sutton PublicSeen 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.

Motion: Require that feature PR's are accompanied by documentation

poll by Tim Sutton Closed Sun 14 Jan 2018 8:41PM

Results

Jürgen E. Fischer

No I don't agree to this proposal.

s/Require/Encourage/

Mathieu Pellerin

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

Matthias Kuhn

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.

Matthias Kuhn

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.

Alessandro Pasotti

No I don't agree to this proposal.

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

Andreas Neumann

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.

Nyall Dawson

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

Martin Dobias

No I don't agree to this proposal.

Same concerns as raised already by others

Nyall Dawson

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?

Alexander Bruy

I have same thought as Nyall. In the past documentation team stated that all they need is a detailed commit messages and corresponding tickets in the documentation repo. And their preference was to write docs by themselves instead of rewriting/adopting texts provided by devs. If I remember correctly, main reason was that documentation from devs is not user-friendly (too technical) and does not follow documentation sctructure/style/etc and as result adopting it requires more time than writting from scratch.

Alessandro Pasotti

I agree in principle but I'd suggest to change the proposal to "we should mandate that any new features being added to QGIS be accompanied by all the information that is needed to produce the user documentation (snapshots, code snippets, workflows etc.).". The rationale (in addition to what already stated by Alex and Mathieu) is doublefold: first the documentation is on a different git repo and it would be difficult (slower) to get a double approval before merging a new feture, second documentation team has its own set of rules and guidelines RST-trickeries that are not always easy to follow for an occasional documentation writer. But I agree that the documentation team should have all the information they need at hand and ready to be integrated.

Tim Sutton

Yes that is a very good modification to the original proposal...

Alessandro Pasotti

@nyalldawson I didn't mean to make screenshots mandatory, but a screenshot or a short video can be occasionally helpful for documentation writers to quickly understand what a new feature brings or what changes to the GUI are to be expected and documented (vector node editing is a good example). I usually find them very useful in some PRs.

Matthias Kuhn

Tim, can you launch a new alternative proposal based on the above? The one of the two proposals with a better Yes/No-Vote ratio shall be accepted, if both get more no votes, nothing will be done.

For the alternative one, I'd like to take the screenshot comment also into consideration, screenshots/screencases are very helpful but should act as orientation, and not necessarily as material for the final documentation (at the documentation team discretion).

Mathieu Pellerin

Agreed on screenshots for all of the above mentioned reasons. We should really encourage devs to attach shots and casts, it makes it easier to understand the goal (s) of a given feature and helps review relevant UI/UX bits too.

Tim Sutton

Will do - and in the larger context I think it is not so important for RST either - rather just having a proper description of the new functionality in plain text that the documentors can embellish instead of figuring out new functionality themselves would be a good solution.

we should mandate that any new features being added to QGIS be accompanied by all the information that is needed to produce the user documentation (snapshots, code snippets, workflows etc.).

poll by Tim Sutton Closed Thu 11 Jan 2018 2:02PM

The rationale (in addition to what already stated by Alex and Mathieu) is doublefold: first the documentation is on a different git repo and it would be difficult (slower) to get a double approval before merging a new feature, second documentation team has its own set of rules and guidelines RST-trickeries that are not always easy to follow for an occasional documentation writer. But I agree that the documentation team should have all the information they need at hand and ready to be integrated.

Results

Nyall Dawson

Yes I agree with this approach

What form would this take? Extra instructions in the GitHub PR template?