Mandating documentation to accompany feature pull requests
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
| Results | Option | % of points | Voters | |||
|---|---|---|---|---|---|---|
| No I don't agree to this proposal. | 64 | 9 | ||||
| Yes I agree to this proposal. | 36 | 5 | ||||
| Not voted | 13 |
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
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.
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.
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.
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
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.
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.
Well said.
Yes that is a very good modification to the original proposal...
@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.
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).
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.
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
| Results | Option | % of points | Voters | |||
|---|---|---|---|---|---|---|
| Yes I agree with this approach | 100 | 4 | ||||
| No I don't agree with this | 0 | 0 | ||||
| Not voted | 23 |
What form would this take? Extra instructions in the GitHub PR template?
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?