Docs meeting agenda

[gundalow]

Closing this Agenda/meeting minutes issue in favor of a new one for 2020. Please go to #521 to add to the agenda or see future meeting minutes.

See https://github.com/ansible/community/blob/master/meetings/README.md for the schedule.

Join us anytime in #ansible-docs on freenode IRC!

[samccann]

2019-10-1

• Discuss filter + tests page and options to split it up https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html
• Possible additional example docs to to help - start of 'data manipulation' examples ansible#46979
• an example of a more useful description - https://www.tailored.cloud/devops/how-to-filter-and-map-lists-in-ansible/

Minutes

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2019-10-01/dawgs_aka_docs_working_group.2019-10-01-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2019-10-01/dawgs_aka_docs_working_group.2019-10-01-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2019-10-01/dawgs_aka_docs_working_group.2019-10-01-14.31.log.html

[samccann]

2019-10-8

• Should we add PR links inside changelogs so users can track back to the code/docs added with the change?
• felixfonein prs in next comment

Minutes

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2019-10-08/dawgs_aka_docs_working_group.2019-10-08-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2019-10-08/dawgs_aka_docs_working_group.2019-10-08-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2019-10-08/dawgs_aka_docs_working_group.2019-10-08-14.31.log.html

[samccann]

2019-10-15

• combine galaxy.com install roles details ansible#63486 - installing roles docs needs knowledgable reviewers

• Fix return value PRs Fix return value documentation (2/2) ansible#63478 and Fix return value documentation (1/2) ansible#63477

• Fix doc - porting_guide_2.8 value example ansible#63493 quick review

• [2.9] crypto modules: improve return value list documentation ansible#63409 - testing first?

• issues triage - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs

Meeting Minutes

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2019-10-15/dawgs_aka_docs_working_group.2019-10-15-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2019-10-15/dawgs_aka_docs_working_group.2019-10-15-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2019-10-15/dawgs_aka_docs_working_group.2019-10-15-14.31.log.html

[samccann]

2019-10-22

• Ansible proposal 68 (see comment below)

• Galaxy docsite updates

• Docs issues triage - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs

Minutes

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2019-10-22/dawgs_aka_docs_working_group.2019-10-22-14.32.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2019-10-22/dawgs_aka_docs_working_group.2019-10-22-14.32.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2019-10-22/dawgs_aka_docs_working_group.2019-10-22-14.32.log.html

[bcoca]

ansible/proposals#68

[samccann]

2019-10-29

• PR docs/docsite: fixes broken docs/docsite/rst/cli references ansible#63697 - fixes edit on Github links on cli pages.

• Docs issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs

• Docs PRs needing reviews/merges - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

Minutes

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2019-10-29/dawgs_aka_docs_working_group.2019-10-29-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2019-10-29/dawgs_aka_docs_working_group.2019-10-29-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2019-10-29/dawgs_aka_docs_working_group.2019-10-29-14.31.log.html

[samccann]

2019-11-12

• Galaxy docs moving to docs.ansible.com/ansible-galaxy/latest

• Docs issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs

• Docs PRs needing reviews/merges - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

Minutes

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2019-11-12/docs_working_group_aka_dawgs.2019-11-12-14.32.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2019-11-12/docs_working_group_aka_dawgs.2019-11-12-14.32.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2019-11-12/docs_working_group_aka_dawgs.2019-11-12-14.32.log.html

[samccann]

2019-12-2

• How to test search improvements w/o messing up search in the interim

• enabling faceted search results

• sanity test addition - verify required field in arspec and docs match

• filter page updates for findabiily

• Docs issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs

• Docs PRs needing reviews/merges - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

Minutes

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2019-12-03/docs_working_group_aka_dawgs.2019-12-03-14.31.html
1Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2019-12-03/docs_working_group_aka_dawgs.2019-12-03-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2019-12-03/docs_working_group_aka_dawgs.2019-12-03-14.31.log.html

[samccann]

2019-12-10

DaWGs schedule

• AGREED: samccann and acozine and anyone else who wants to play along - made New Year resolution to close 24 docs issues each in 2020

PR review

• fix rendering of GOOD/BAD code for regex_replace examples ansible#65654
• Update playbooks_filters.rst ansible#65626 is failing due to indentation errors
• Make docs testing_formatter script more portable ansible#65112 this one for anyone else around
• https://www.irccloud.com/pastebin/M9l2nTvB/
• VMware: add note to vmware_guest faq ansible#65569
• VMware: Cautions on using VMware modules with standalone ESXi ansible#64643 (comment)
• next week's meeting will be the last meeting of 2019

Actions

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2019-12-10/docs_working_group_aka_dawgs.2019-12-10-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2019-12-10/docs_working_group_aka_dawgs.2019-12-10-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2019-12-10/docs_working_group_aka_dawgs.2019-12-10-14.31.log.html

[samccann]

2019-12-17

Status updates

• part 2 of the User Guide overhaul is out and published on devel. Comments always welcome. More improvements to come (thanks acozine !!)
• https://docs.ansible.com/ansible/devel/user_guide/index.html
• still poking away at triming down site search to one option on docs.ansible.com/ansible. Currently there are two.
• • python script to turn irc meeting minutes into markdown
• • https://gist.github.com/Qalthos/7d9c8256b7040dba1438172771aea663
• last meeting of the calendar year! Next DaWGs meeting will be in January
• Automation Hub docs moving along and will eventually move back upstream to Galaxy docs

Docs Issues and PRs

• we currently have 226 docs issues open and looking for kind souls to help resolve them
• https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs
• Docs PRs running at 105 today
• https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
• goal is to get and then keep this down to under 75... any/all help welcome (reviews, comments, approvals etc. Everything helps move them along)

Open Floor

• documentation for 'devel' is updated/republished nightly to docs.ansible.com. Merged PRs show up there. If the PR should be in 'latest' or some other version, please backport it.
• https://docs.ansible.com/ansible/latest/community/development_process.html#backport-process
• [2]Collections documentation suggestions ansible#60282

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2019-12-17/docs_working_group_aka_dawgs.2019-12-17-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2019-12-17/docs_working_group_aka_dawgs.2019-12-17-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2019-12-17/docs_working_group_aka_dawgs.2019-12-17-14.31.log.html

[samccann]

2020-01-07

Status Updates

• https://github.com/acozine/ansible/tree/user_guide_reuse
• Reuse section of user guide being revamped by acozine
• https://github.com/acozine/ansible/tree/user_guide_reuse If you want to give it a try. PR will come once Tags page gets more docs love
• will need deep reviews of Includes vs Imports section
• Search facets still not working on swiftype search option. Opening a support ticket for help. (Trying to trim us down to one site search)

Galaxy Docs

• Clarify how to use the Galaxy token ansible#65961
• Documentation should state what tests are run galaxy#2182
• • galaxy documentation on https://galaxy.ansible.com/docs/ needs updating, but do we update there or wait for galaxy upstream decisions?
• we can document Documentation should state what tests are run galaxy#2182 in our collections docs on docs.ansible.com once we have more detail on what was being tested and what went wrong etc.
• https://github.com/ansible/galaxy/tree/devel/galaxy/importer/ <= see linter(yamllint) and tests dirs, those are what get used on import

Issues and PRs

We have 231 issues and growing. Please adopt an issue or three to fix :-)

Jinja2 is becoming Jinja

• Jinja2 renaming to Jinja ansible#66163

Docs PRs

• We have 97 open docs PRs thanks to acozine working her little holiday magic to keep them down below 100.
• https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

broken links

• used blc locally against a build to find and fix some broken links (and we have a fair few)

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-01-07/docs_working_group_aka_dawgs.2020-01-07-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-01-07/docs_working_group_aka_dawgs.2020-01-07-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-01-07/docs_working_group_aka_dawgs.2020-01-07-14.31.log.html

[samccann]

2020-01-14

Status Updates

• top left search box on devel is now running swiftype search. Feedback most welcome
• Added writing guidelines for search optimization
• https://docs.ansible.com/ansible/devel/dev_guide/style_guide/search_hints.html

how ansible executes

• https://docs.ansible.com/ansible/latest/dev_guide/developing_program_flow_modules.html
• above link is a possible home for a deep dive on how ansible executes
• https://www.reddit.com/r/ansible/comments/eo6lwq/why_is_ansible_user_not_defined_when_accessed/fe9dcci/
• https://www.reddit.com/r/ansible/comments/eo6lwq/why_is_ansible_user_not_defined_when_accessed/fe9dcci/ - where the request came from
• https://www.reddit.com/r/ansible/comments/eo6lwq/why_is_ansible_user_not_defined_when_accessed/
• consider a user level page to introduce the ansible execution tidbits, then a deeper dive in the dev guide

latest user guide updates

• http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_reuse.html
• looking for feedback on Docs: User Guide overhaul, part 3 ansible#66371
• http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_reuse_roles.html especially
• http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_tags.html as well

linting examples in the documentation

• would be great to run ansible-lint against doc examples in .rst and module docstrings. May require some scripts to do this w/o having to move all examples into separate .yml files
• Evaluate top 10 docsite page hits to improve overall flow of content ansible#58687 - lists top 10 doc pages for Ansible. Good place to start making improvements
• docs: lint all examples ansible#66474
• docs: lint all examples ansible#66474 - new issue to track ansible-lint on docs

open floor

• correct indentation of tasks definition in vars_files example ansible#66408
  Actions

---

@cbudz to draft a topic to cover this

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-01-14/docs_working_group_aka_dawgs.2020-01-14-14.32.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-01-14/docs_working_group_aka_dawgs.2020-01-14-14.32.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-01-14/docs_working_group_aka_dawgs.2020-01-14-14.32.log.html

[samccann]

2020-01-21

Status updates

• User Guide revamp still ongoing.
• minor heading adjustments to Install guide for search improvements
• continuing work on the Collections Docs pipeline (bringing module docs from inside collections into docs.ansible.com. Goal is to have somethign working by middle of March
• PR for latest User Guide changes if anyone has time/bandwidth to review: Docs: User Guide overhaul, part 3 ansible#66371

open docs PRs

• https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
• docs PRs above 100... review review review please!
• https://github.com/ansible/ansible/pull/66658/files
• https://www.irccloud.com/pastebin/hf7blqV5/

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-01-21/docs_working_group_aka_dawgs.2020-01-21-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-01-21/docs_working_group_aka_dawgs.2020-01-21-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-01-21/docs_working_group_aka_dawgs.2020-01-21-14.31.log.html

[samccann]

2020-01-28

Status Updates

• left hand search is now using swiftype search on 'latest'
• User Guide PR merged!! Improved the flow of sections of the Ansible User Guide
• continued work coming on other sections of the User Guide
• work coming on updating collections doc and creating ansible_user doc
• based on this: https://www.reddit.com/r/ansible/comments/eo6lwq/why_is_ansible_user_not_defined_when_accessed/

Search box on docs.ansible.com

• https://www.reddit.com/r/ansible/comments/eu4jat/mindblowing_docsansiblecom_does_not_have_a_search/
• each docsite (ansible, galaxy, tower) has its own search but nothing on the top page allows for a cross-site search)
• docs.ansible.com is also a confusing page with a lot of content. needs to be simplified/redesigned
• on duckduckgo, you can type !ansible loops and get search results from docs.ansible.com only
• on duckduckgo, you can also use !galaxy or !ansiblemod yum to get directly to the yum module docs page for example

View vs Edit Github links

• would be nice if a reader has the option to click view on github instead of always edit on gitub
• if you aren't logged into github, the Edit on Github link takes you to the login page, not the content you wanted to edit. So you have to be logged in to even view the page
• possibly this is useful for module pages, where a developer wants to quickly scan the code but not edit it.

Putting module names in changelog fragments

• some changelog fragments talk about adding a parameter etc, but don't actually name the module it applies to
• 👍 update the changelog guidelines to ensure it says included all relevant info including module names etc
• 👍 find a way to spread this need to those who merge module changes etc

Open Floor

• for Edit vs View on Github - an example would be finding a doc change and wanting to find the code change that matched it. So view the file on github, find the commit/pr, and find what code changed underneath.

Docs Issues and PRs

• we have 225 open Docs issues and 102 open docs PRS

Logs

Minutes: https://meetbot-raw.fedoraproject.org/ansible-docs/2020-01-28/dawgs_%28documentation_working_group%29.2020-01-28-14.34.html
Minutes (text): https://meetbot-raw.fedoraproject.org/ansible-docs/2020-01-28/dawgs_%28documentation_working_group%29.2020-01-28-14.34.txt
Log: https://meetbot-raw.fedoraproject.org/ansible-docs/2020-01-28/dawgs_%28documentation_working_group%29.2020-01-28-14.34.log.html

[pilou-]

• variables defined with 'vars:' keyword below 'role:' have unexpected values when used in imported/included roles ansible#50278 should not role parameters be documented ?

[samccann]

Closing this Agenda/meeting minutes issue in favor of a new one for 2020. Please go to #521 to add to the agenda or see future meeting minutes.
(@pilou- I added your comment to next week's agenda, thanks!)