Improve Access and User Consent document

[chrishowell]

What type of PR is this?

documentation

What this PR does / why we need it:

Defines terms and keeps them consistent throughout, improves clarity in English writing.

Which issue(s) this PR fixes:

#98

Special notes for reviewers:

Changelog input

 release-note access-and-user-consent documentation update

Additional documentation

docs

[AxelNennker]

Hi @chrishowell
could you please split the PR into a "better English one" and one or more for consistent use of terms and better definitions?
I would like to get the easy stuff approved and then start the discussion on the rest. Which might still lead to some discussion. Thanks for the PR. I am a bit overwhelmed by it

[jpengar]

@chrishowell @AxelNennker This is a great contribution, thank you Chris!
I agree with Axel, it will be much easier to handle if we isolate the proposed changes in different PRs. The "better English" one will probably be the easiest to approve. However, the one about the terms and definitions (saying that I pretty much agree with the ones you propose), there is a specific #98 issue to revisit terms and definitions and I can imagine that it will require further discussions.

On the other hand, I've labeled the PR with ICM backlog as it would have to be addressed in the next release. We are already closing the second release candidate of current release 0.2.0-rc.2, which is only intended for bug fixes. Also, among the changes you suggested, some of them have greater impact than they look:

• Changing the title of the Purpose section would change the link reference to that section, and would require updating existing references to that section in all other documents in all subprojects that point to it. That's not possible for this meta release at this stage.
• Also, you propose changes to the info.description template, which is included in all CAMARA APIs. This is a very sensitive text to change, as it represents the ICM agreement between many participants. And this text is copied into all API specifications. So if it is changed, it would have to be carefully revised and updated in all API subprojects. So that would certainly be work for another release -> UPDATE: BTW, there is a specific issue to revisit this template *in the backlog The wording in the Mandatory template for info.description is unclear #178

[chrishowell]

Thanks for reviewing :) it's a bit difficult to split this into multiple PRs as the 'better English' comes with using defined terms..

[jpengar]

Thanks for reviewing :) it's a bit difficult to split this into multiple PRs as the 'better English' comes with using defined terms..

@chrishowell As discussed by the team in yesterday's WG call, in order to move things forward, could you split the content of this PR into three:

• One focused on just updating the terms and definitions. So that the WG can agree on the terms to be used in the rest of the documentation. Please keep the same changes you propose in the PR.
• Another editorial one, simply including the same "better English" changes you propose in this PR. You can assume for the moment that the terms and definitions are the ones you proposed. And then it may need some adjustments if something is changed in the previous PR.
• And finally, another independent PR just for changes in the info.description template, which could also fix other issues like The wording in the Mandatory template for info.description is unclear #178.