ansible-documentation
ansible-documentation copied to clipboard
[WIP, needs vote before merging] collection_requirements.rst: update
It's time to revise and update the requirements if needed. Forum topic.
Goals:
- Simplify it if possible (content, wording), make it easier to read
- Exclude irrelevant requirements (including those that don't work/very hard to control)
- Make maintainers and reviewers 's lives easier
Any suggestions are appreciated (in not touched parts as well)
Post tasks:
- [ ] Update https://github.com/ansible-collections/overview/blob/main/collection_checklist.md after merging this PR if needed.
Another general comment. The top sections are clear on MUST and SHOULD but as it gets later in the page, there is a lot of contextual information that tends to clutter the MUST etc. So maybe each section should start with the MUST sentences, and then under each, indent, and add the context.
So for example, under python compatibility , it could have controller environment and other environment subheadings with their MUST statements. Then under the MUST, indent and add the contextual details of what each python environment means.
The goal would be that a knowledgable collection maintainer can more easily skim the document to verify they meet all the MUST statements. But a newer collection creator still has the details they need to understand each MUST statement.
Looks good @Andersson007 I've read through this a couple of times to try and come up with comments other than grammar nits but it seems fine. It looks a bit more straightforward now. I'll wait and see how the vote goes before approving in case there are additional changes.
it's still WIP, the call was about bringing up thoughts of what else to kick out/simplify, just a fyi, thanks for the feedback!
Another general comment. The top sections are clear on MUST and SHOULD but as it gets later in the page, there is a lot of contextual information that tends to clutter the MUST etc. So maybe each section should start with the MUST sentences, and then under each, indent, and add the context.
So for example, under python compatibility , it could have controller environment and other environment subheadings with their MUST statements. Then under the MUST, indent and add the contextual details of what each python environment means.
The goal would be that a knowledgable collection maintainer can more easily skim the document to verify they meet all the MUST statements. But a newer collection creator still has the details they need to understand each MUST statement.
@samccann something like https://github.com/ansible/ansible-documentation/pull/1459 ? (not sure if it's a good idea to create a separate PR for that though..). Folks please take a look
@Andersson007 yes, that other PR makes that section easier to read!