DaWGs (Documentation Working Group) Meeting Agenda 2022

[samccann]

This agenda is old. The new agenda for 2023 is at https://github.com/ansible/community/issues/678

[samccann]

2022-01-04

opening chatter

• new agenda issue for the new year! https://github.com/ansible/community/issues/643

semantic markup

• example - https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_set_module.html#parameters
• here's another example with lists and suboptions: https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_sets_module.html#parameters

documentation work

• please help with the docs issue backlog - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs including some easyfix items https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs+label%3Aeasyfix
• comments/approvals of docs PRs from the technical perspective always helps to move them to final merging! - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs_only
• https://github.com/ansible/ansible-documentation/issues/48
• https://docs.ansible.com/ansible/latest/user_guide/intro_getting_started.html

Docs tooling

• example of the docs workflow in action for a collection-level PR - https://github.com/ansible-collections/community.docker/blob/main/.github/workflows/docs-pr.yml
• another example which includes a publish step, and some customization (I commit the output of antsibull sphinx-init), it's not much more complicated: https://github.com/ansible-collections/community.hashi_vault/blob/main/.github/workflows/docs.yml
• the shared actions and workflows live in the community.hashi_vault repo, but they should be moved to their own project(s) so that they can be treated as the separate projects they are
• The actions are here: https://github.com/ansible-collections/community.hashi_vault/tree/main/.github/actions/docs
• hared workflows are here (they must be mixed with non-shared workflows, so I pre-pended all with _shared): https://github.com/ansible-collections/community.hashi_vault/tree/main/.github/workflows

Actions

• [x] @@samccann to push more on the semantic markup review internally and include the example links
• [x] @acozine to work on creating command cheat-sheet for that issue

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-01-04/documentation_working_group_aka_dawgs.2022-01-04-15.59.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-01-04/documentation_working_group_aka_dawgs.2022-01-04-15.59.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-01-04/documentation_working_group_aka_dawgs.2022-01-04-15.59.log.html

[samccann]

Listing still-open action items from 2021 so I don't have to look at the old issue anymore :-):

• [ ] @samccann improve visibility of expand/collapse PR - https://github.com/ansible/ansible/pull/75695
• [x] @samccann find a way to use remindbot with newsbot to add Help Wanted on easyfix items each week

[samccann]

2022-01-11

Community guide docs

• starting a project to combine community docs from ansible/ansible and other repos where it exists. https://hackmd.io/3Cvy2N8tTfSrUzqYZmfEHA
• step 1 - combine the info
• step 2 - publish (possibly from different repos)

Better changelog guidelines

• We had some feedback to create better guidance for developers on what to include in changelog fragments - https://hackmd.io/ZdymdeUSQNeM0hMjsn7vig
• some ansible-core changelogs impact other developers. Most/all collection changelogs impact end users

DocTools

• simplified module tables are up on devel! https://docs.ansible.com/ansible/devel/collections/community/general/aix_lvol_module.html
• good samples of this https://docs.ansible.com/ansible/devel/collections/community/crypto/acme_certificate_module.html#parameters and https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/hashi_vault_lookup.html#parameters and https://docs.ansible.com/ansible/devel/collections/cisco/ios/ios_bgp_address_family_module.html#parameters

Open Floor

• The docs build github stuff has been moved to its own repo: https://github.com/ansible-community/github-docs-build
• this allows collection owners to create collection docs during the PR to validate they work
• documentation on this feature just starting but is at https://github.com/ansible-community/github-docs-build/wiki

Actions

• [x] @@samccann to turn community docs idea into a community-topic proposal and share on bullorn and reddit
• [x] @@samccann to turn changelog guidance into community-topic to widen discussion/feedback

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-01-11/documentation_working_group_aka_dawgs.2022-01-11-16.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-01-11/documentation_working_group_aka_dawgs.2022-01-11-16.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-01-11/documentation_working_group_aka_dawgs.2022-01-11-16.00.log.html

[samccann]

2022-01-18

Community examples

• we're open for community base Ansible examples here - https://github.com/ansible-community/community-examples
• https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+survey
• a couple more docs survey feedback issues we could use help on - https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+survey
• splitting up the community guide into getting started, core, and collection contributor guides - https://github.com/ansible/ansible/pull/76764 (WIP)

generating docs for collections

• GitHub actions and reusable workflows you can use to generate documentation in your own collection repository on GitHub -https://github.com/ansible-community/github-docs-build
• actively in use in community.docer and community.hashi_vault
• https://github.com/ansible-community/github-docs-build/wiki
• some early docs available at https://github.com/ansible-community/github-docs-build/wiki

semantic markup

• we found out definitively that this will impact Automation Hub/ GalaxyNG so need to coordinate with that team
• if anyone has additional ideas for semantic markup improvements, now's the time to get them in before the design goes for internal review with the GalaxyNG teeam!
• proposal - https://hackmd.io/VjN60QSoRSSeRfvGmOH1lQ

Actions

• [x] @samccann to change room alert to 31 hrs for help wanted nag
• [x] @felixfontein to write up an addition to the semantic markup to support seealso: for plugins as well as modules
• [ ] @samcann acozine - to review https://github.com/ansible/ansible/issues/76609 in terms of how we can add to the cheatsheet and/or create split controller docs to help out here (and eventual URL added to ansible-test --help1 output

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-01-18/documentation_working_group_aka_dawgs.2022-01-18-16.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-01-18/documentation_working_group_aka_dawgs.2022-01-18-16.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-01-18/documentation_working_group_aka_dawgs.2022-01-18-16.00.log.html

[samccann]

2022-01-25

Documentation updates

• start of splitting community guides - https://docs.ansible.com/ansible/devel/index.html
• follow this topic to discuss this - https://github.com/ansible-community/community-topics/issues/60
• supports people as they move "up the levels", from newcomer, to Ansible user, to community member, to contributor/WG member/maintainer with the way we have all on docs.ansible.com/ansible today
• with a single search engine and unified TOC
• another aspect of this - other projects will be coming online. Contributing to (say) AWX or Dev-tools doesn't have anything to do with ansible-core.

changelog fragments

• please add your comments to https://github.com/ansible-community/community-topics/issues/64

examples repo

• we have the start of a repo of community-curated examples - https://github.com/ansible-community/community-examples
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

doctools

• https://github.com/ansible-collections/community.hashi_vault/pull/211

Actions

• [x] @samccann to start (or revamp) a hackmd to get some ideas down on separating the docsite up

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-01-25/documentation_working_group_aka_dawgs.2022-01-25-15.58.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-01-25/documentation_working_group_aka_dawgs.2022-01-25-15.58.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-01-25/documentation_working_group_aka_dawgs.2022-01-25-15.58.log.html

[samccann]

2022-02-01

opening chatter

• Agenda https://github.com/ansible/community/issues/643#issuecomment-1021482151

Documentation updates

• We've been looking at canonical url support to the Ansible 2.3 and 2.4 docs sites (as Google links to the old docs sometimes). To do this we'd need to backport the sphinx theme, which we've not looked into yet
• https://github.com/ansible/ansible/pull/49190 is where the work was done originally
• we still have problems with older docs coming up first in search results (eg google "ansible authorized_key" and you get 2.3 or 2.4 at the top results)
• https://github.com/ansible-community/antsibull-docs/issues/66
• 0.40.1 -> 0.40.2 fixes broken HTML - https://github.com/ansible-community/antsibull-docs/issues/66
• https://github.com/ansible-community/antsibull/releases/tag/0.40.1 says "Fix bug in collection enum for docs generation, which caused role FQCNs to be mangled (#379)."
• 0.40 to 0.40.1 - https://github.com/ansible-community/antsibull/releases/tag/0.40.1
• https://github.com/ansible/ansible/pull/76675
• looking for feedback - PR that closes 3 open issues, adding support for both more lenient, and more strict docs builds, and specifying a specific antsibull version (all helpful for expanding the scope of scenarios for building docs: https://github.com/ansible-community/github-docs-build/pull/27
• also looking for feedback on a comment on an open issue with an idea of how to solve a tricky problem around the shared GitHub workflows referencing the actions in a consistent way (this is more in the weeds of GHA stuff, not so interesting around docs directly): https://github.com/ansible-community/github-docs-build/issues/4#issuecomment-1024974751

Actions

• [x] @samccann to book time with search expert to help us reduce search results to ancient docs
• [x] @samccann gunalow - get his cannonical url for 2.3 work staged on test etc
• [x] @gundalow to look if redirects are broken
• [x] @samccann to test https://github.com/ansible/ansible/pull/76759 for the updated antsibull release

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-02-01/documentation_working_group_aka_dawgs.2022-02-01-16.04.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-02-01/documentation_working_group_aka_dawgs.2022-02-01-16.04.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-02-01/documentation_working_group_aka_dawgs.2022-02-01-16.04.log.html

[samccann]

2022-02-08

Documentation Updates

• -collection maintainers guide PR - https://docs.ansible.com/ansible/devel/index.html and staged at http://docs.testing.ansible.com/ansible/devel/community/maintainers.html
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
• we have the start of a repo of community-curated examples - https://github.com/ansible-community/community-examples
• https://github.com/ansible-community/community-examples/tree/main/examples/core

doc tooling updates

• favicon fix in the works - https://github.com/ansible-community/sphinx_ansible_theme/pull/49
• after merging, we need PR to bump theme version in ansible/ansible and test, then decide whether to backport to 2.12.

Open Floor

• 2.13 branch pull scheduled for 3/28 so changes for antsibull and other tooling that needs core changes should happen before then

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-02-08/documentation_working_group_aka_dawgs.2022-02-08-15.59.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-02-08/documentation_working_group_aka_dawgs.2022-02-08-15.59.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-02-08/documentation_working_group_aka_dawgs.2022-02-08-15.59.log.html

[samccann]

2022-02-15

Documentation updates

• looking for ways to expand this group and get more docs contributions. Ideas welcome!
• should we be more async? How do we do async other than community-topics for things that need broad discussion?
• collection maintainers guide PR - https://docs.ansible.com/ansible/devel/index.html - hope to merge soon and then stub out the same content on community-docs repo.

Publishing non-versioned docs on a versioned docsite

• we have multiple pages on docs.ansible.com that are not tied to the core or Ansible release. Today, we publish them only to devel but this confused at least one person recently
• https://docs.ansible.com/ansible/latest/porting_guides/porting_guides.html
• we did this devel-only publishing because PRs weren't being backported so latest frequently had stale info, and most of these are not version-specific anyway
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

Doctools updates

• adding extra links to collection and module docs pages - https://github.com/ansible-community/antsibull/pull/355
• to see this in action - https://ansible.fontein.de/collections/community/dns/
• Improve attributes table PR - https://github.com/ansible-community/antsibull/pull/401 looks good!
• https://github.com/ansible-community/antsibull/pull/355

open Floor

• https://github.com/ansible-collections/community.general/pull/4203 <= example documenting filter that is in 'multifilter file'
• https://github.com/ansible-collections/community.general <= example documenting filter that is in single file
• https://github.com/ansible-collections/community.general/pull/4202 sorr, that one

Actions

• [x] @samccann to investigate an instruqt tutorial on contributing to docs
• [x] @samccann to open community-topic to debate community guides on devel only or regular backports to latest etc
• [x] @samccann to followup with community team on best ways to give shout outs to new contributors and those in top 10 so to speak

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-02-15/documentation_working_group_aka_dawgs.2022-02-15-15.59.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-02-15/documentation_working_group_aka_dawgs.2022-02-15-15.59.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-02-15/documentation_working_group_aka_dawgs.2022-02-15-15.59.log.html

[felixfontein]

• [x] https://github.com/ansible-community/antsibull/pull/401

[samccann]

2022-02-22

doctools

• https://github.com/ansible-community/antsibull/pull/355
• open question - do we want all buttons on all module pages, or just the current 'click here to edit' that the current examples have
• we're looking at https://www.home-assistant.io/integrations/esphome/ for inspiration on these links/buttons. Goal is to make it as easy as possible for someone to contribute/open an issue against modules and plugins
• https://en.wikipedia.org/wiki/Aphantasia

unversioned docs

• community-topic to discuss if we want to have unversioned docs (like community/contributor guides) - https://github.com/ansible-community/community-topics/issues/68 Please add your comments there.

documentation Updates

• crafting better changelog fragments PR - ttps://github.com/ansible/ansible/pull/77040

Actions

• [x] @samccann to have a PR for how to edit collection docs once https://github.com/ansible-community/antsibull/pull/355 merges

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-02-22/documentation_working_group_aka_dawgs.2022-02-22-15.59.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-02-22/documentation_working_group_aka_dawgs.2022-02-22-15.59.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-02-22/documentation_working_group_aka_dawgs.2022-02-22-15.59.log.html

[samccann]

2022-03-01

Documentation updates

• added accessibility guidelines to Ansible docs style guide.
• daylight savings time changes coming up soon. We need to decide if we shift this meeting so it stays the same after that or ...not.
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

doctools

• Jenkins docs builds are busted again. I updated them all to use centos8-stream - http://mirror.centos.org/centos/8-stream/
• community-topic to discuss if we want to have unversioned docs (like community/contributor guides) - https://github.com/ansible-community/community-topics/issues/68 Please add your comments there.
• adding extra links to collection and module docs pages - https://github.com/ansible-community/antsibull/pull/355
• an example of this in action - https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_module.html#collection-links

semantic markup

• semantic markup will not be on the Red Hat product roadmap this year.
• community will need to consider a redesign for 'opt in' or delay this feature until it can be timed with the product roadmap down the road

Actions

• [x] @samccann to ping individuals not here about DST time shift for the meeting
• [x] @samccann to ping 'someone in the know' about using centos8-stream for production docs
• [ ] @samccann to investigate creating a GitHub Actions workflow that triggers on PR merge of specific paths for keeping porting guide up todate in latest etc

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-03-01/documentation_working_group_aka_dawgs.2022-03-01-15.59.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-03-01/documentation_working_group_aka_dawgs.2022-03-01-15.59.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-03-01/documentation_working_group_aka_dawgs.2022-03-01-15.59.log.html

[samccann]

• [x] Time change coming (US on March 13th, Europe on March 27th) -

[samccann]

2022-03-08

Documentation updates

• Meeting time will say the current UTC until Europe goes to DST (March 27th) so for those in the US, this meeting will be one hour later for 2 weeks.
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

semantic markup

• as a reminder, the proposal as currently designed is not a part of the Ansible/RH roadmap for this year
• --json basically dumps the documentation as-is from the plugins, and if the plugin documentation uses semantic markup, it's in the --json output
• So we are on hold with semantic markup until it lands in an official product roadmap

redirects

• to get Ansible collection redirects working 'way back in ansible 3' we had to remove the redirects that went from old docs.ansible.com/ansible/foo to docs.ansible.com/ansible//foo
• https://github.com/ansible/ansible/issues/77204
• redirect removed by https://github.com/ansible/docsite/pull/38
• the relevant diffs - https://pastebin.com/kMvgKFLJ

doctools

• looking for help on https://github.com/ansible/ansible-documentation/issues/144. Likely requires coding but not even sure where
• take a look at https://github.com/ansible-community/antsibull/pull/355 and post comments or +1s etc

Open Floor

• https://github.com/ansible-community/antsibull/pull/355/files#diff-81dcd7b3ffe8fe9d6bc5962ad8c9dc1f2053087277f96d24eeffa14549d3f18dR35-R62 <-- that's the stuff for ansible.builtin
• https://ansible.fontein.de/collections/ansible/builtin/
• builtin links/buttons - https://ansible.fontein.de/collections/ansible/builtin/

Actions

• [x] @samccann to ask webserver folks for access logs to see how often these old urls are used
• [x] @samccann to check web analytics for these older unversioned urls
• [x] @all - review the ansible.builtin links/buttons here - https://github.com/ansible-community/antsibull/pull/355/files#diff-81dcd7b3ffe8fe9d6bc5962ad8c9dc1f2053087277f96d24eeffa14549d3f18dR35-R62

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-03-08/documentation_working_group_aka_dawgs.2022-03-08-15.58.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-03-08/documentation_working_group_aka_dawgs.2022-03-08-15.58.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-03-08/documentation_working_group_aka_dawgs.2022-03-08-15.58.log.html

[samccann]

NOTE: we will switch the UTC time of this meeting once Daylight savings happens in Europe (March 27th) so that the meeting time remains constant throughout the year for those places using DST.

[samccann]

2022-03-15

Documentation updates

• Meeting time will say the current UTC until Europe goes to DST (March 27th) so for those in the US, this meeting will be one hour later for another week
• we are considering moving EOL docs to an archive site to keep them available, but not in search results
• biggest question - is it worth all this effort and long term maintenance to create this archive site ? Are the older EOL docs causing that much problem in search?
• one of the search problem areas are for specific built-in modules - they are popular and have been for ages so search results can pick up very old docs for these
• please comment on the issue so we can track community feedback on this
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

Versioned docs on collections

• https://docutils.sourceforge.io/docs/ref/rst/directives.html#include

Open Floor

• last chance to comment on the format for the yaml file that includes links on collection docs pages - https://github.com/ansible-community/antsibull/pull/355

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-03-15/documentation_working_group_aka_dawgs.2022-03-15-16.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-03-15/documentation_working_group_aka_dawgs.2022-03-15-16.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-03-15/documentation_working_group_aka_dawgs.2022-03-15-16.01.log.html

[samccann]

2022-03-29

Documentation updates

• one old action item to review https://github.com/ansible/ansible/issues/76609 in terms of how we can add to the cheetsheet and/or create split controller docs to help out here (and eventual url add to ansible-test --help output)
• proposed Docs priorities for the coming 18 months or so - https://github.com/ansible-community/community-topics/issues/81
• next emphasis on 'getting started' guides - focusing on new users, contributors, developers.
• stable-2.13 branch pulled. Doing docs backports weekly until Ansible 6 releases.

Pip only install docs

• stable-2.13 branch pulled. Doing docs backports weekly until Ansible 6 releases.
• docs install trimmed to pip only - https://github.com/ansible-community/community-topics/issues/83 -

Ending devel-only docs

• seems unpopular that we have a few docs only on devel. Starting in 2.13 as latest, we will stop this trend and go back to keeping porting guides and release/maint pages up to date in lateset and devel. Will not be going to older releases.
• longer term, we'll investigate an unversioned approach, per comments in - https://github.com/ansible-community/community-topics/issues/68

doctools

• we have buttons and extra links on collection pages now! https://docs.ansible.com/ansible/devel/collections/community/dns/index.html

Open Floor

• https://github.com/ansible/ansible/pull/77352

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-03-29/documentation_working_group_aka_dawgs.2022-03-29-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-03-29/documentation_working_group_aka_dawgs.2022-03-29-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-03-29/documentation_working_group_aka_dawgs.2022-03-29-15.01.log.html

[samccann]

2022-04-05

Troubleshooting collection CI problems

• our collection development docs may assume a deeper level of ansible experience than actual new collection owners have
• https://adhawkins.github.io/ansible-borgbase/collections/adhawkins/borgbase/index.html#plugins-in-adhawkins-borgbase
• https://www.ansible.com/products/ansible-community-training has "Ansible Community - Creating your own Collection"
• https://play.instruqt.com/redhat/tracks/ansible-community-creating-your-own-collection is the link directly to the lab
• tutorial on creating a collection https://play.instruqt.com/redhat/tracks/ansible-community-creating-your-own-collection

Ansible docs project board

• • is anyone accessing/using the Docs github project board? is it useful? - https://github.com/ansible/ansible/projects/27?
• example of a project board using the new format -https://github.com/orgs/ansible-collections/projects/6/views/1
• • general consensus is that a better project board is not a bad thing, but no one feels they would necessarily use it vs the existing DaWGs agenda/meeting minutes

doctools

• splitting up the antsibull package - https://github.com/ansible-community/antsibull/issues/410
• currently planning to split up antsibull in probably three parts: antsibull-core (some shared code), antsibull-docs (with the antsibull-docs CLI tool), and antsibull (with the antsibull-build and antsibull-lint CLI tools, the latter being deprecated)
• this would mean `antsibull-doc updates would no longer impact the the publicly visible changelog sanity test or the collections test container

Actions

• [x] @put more troubleshooting breadrumbs in the developing/releasing collections to run common ansible-test sanity checks locally first.
• [x] @samccann - verify if Zuul is available for automating any collection publishing to galaxy
• [ ] @samccann make sure developing collection docs points to the template
• [x] @- link to the tutorials at https://www.ansible.com/products/ansible-community-training

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-04-05/documentation_working_group_aka_dawgs.2022-04-05-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-04-05/documentation_working_group_aka_dawgs.2022-04-05-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-04-05/documentation_working_group_aka_dawgs.2022-04-05-15.01.log.html

[samccann]

2022-04-19

Documentation Updates

• • very rough draft of distro installs - https://github.com/ansible/ansible/pull/77567
• proposed Docs priorities for the coming 18 months or so - https://github.com/ansible-community/community-topics/issues/81
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

doctools

• splitting up the antsibull package - https://github.com/ansible-community/antsibull/issues/410
• considering removing known_good_reqs.txt and using the code-smell requirements file instead - https://github.com/ansible/ansible/blob/devel/test/sanity/code-smell/docs-build.requirements.txt

Actions

• [x] @samccann to find a way to incorporate the docs priority list into the docs github project board for tracking

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-04-19/documentation_working_group_aka_dawgs.2022-04-19-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-04-19/documentation_working_group_aka_dawgs.2022-04-19-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-04-19/documentation_working_group_aka_dawgs.2022-04-19-15.00.log.html

[samccann]

2022-04-26

Documentation Updates

• distro install page published - https://docs.ansible.com/ansible/devel/installation_guide/installation_distros.html
• • Is it time to put some docs around how to test collection documentation? see https://hackmd.io/w6JSHW_XRzi9cBZtoN4snA for very rough draft.
• https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/docsite/contributor_guide.html#collection-docsite
• • Documenting wheels - do we need to mention this in the basic pip install, or is it noise for most users? Do we put pip download in a supplemental install page to say that's how you get everything?

docs builds

• adding known_good to stable-2.10 in order to get the docs buildable again.
• replacing 'known_good' reqs file for docs with sanity-test reqs file so we don't need to keep them in sync - https://github.com/ansible/ansible/pull/77612#
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

doctools

• splitting up the antsibull package - https://github.com/ansible-community/antsibull/issues/410

Actions

• [x] @samccann to move https://hackmd.io/w6JSHW_XRzi9cBZtoN4snA into official docs and maybe point to https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/docsite/contributor_guide.html#collection-docsite as an example of how a collection owner can document this.

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-04-26/documentation_working_group_aka_dawgs.2022-04-26-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-04-26/documentation_working_group_aka_dawgs.2022-04-26-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-04-26/documentation_working_group_aka_dawgs.2022-04-26-15.00.log.html

[samccann]

2022-05-03

Documentation Updates

• working on backports and prep for core-2.13 and Ansible 6 releases
• will revert back to keeping porting guide and release/maintenance pages updated in devel AND latest.

doctools

• supporting sidecar docs - https://github.com/ansible-community/antsibull-docs/pull/6
• https://ansible.fontein.de/collections/ansible/builtin/ternary_filter.html#input for example has all three

github docs build update

• https://github.com/ansible-community/github-docs-build/wiki/Getting-started-with-GitHub-Pages
• https://github.com/ansible-community/github-docs-build/tree/main/samples
• getting started on github pages publishing for collection docs PR - https://github.com/ansible-community/github-docs-build/wiki/Getting-started-with-GitHub-Pages
• sample workflows for collection maintainers to grab and use:
• https://github.com/ansible-community/github-docs-build/tree/main/samples

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-05-03/documentation_working_group_aka_dawgs.2022-05-03-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-05-03/documentation_working_group_aka_dawgs.2022-05-03-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-05-03/documentation_working_group_aka_dawgs.2022-05-03-15.01.log.html

[samccann]

2022-05-10

Documentation updates

• moving collection-level dev guides out to their collection repos - https://github.com/ansible-community/community-topics/issues/91
• starting the new getting started guide. Add comments to the issue if you have ideas/suggestions - https://github.com/ansible/ansible/issues/77681
• down to 100 open docs issues! (from 133).
• reddit feedback on getting started - https://www.reddit.com/r/ansible/comments/udy8ke/feedback_wanted_updating_the_ansible_getting/
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

Doctools

• https://github.com/ansible-community/antsibull-docs/pull/6
• sidecar docs are a 2.14 feature so docsite support will not show up until 2.14 releases, except on devel at some point
• https://github.com/ansible-community/antsibull-docs/pull/8
• community.aws is partially using the docs build work by briantist
• support coming for seealso in plugin docs
• this addition has no impact on AH etc as they will need to support their own version of seealso when they support sidecar docs

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-05-10/documentation_working_group_aka_dawgs.2022-05-10-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-05-10/documentation_working_group_aka_dawgs.2022-05-10-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-05-10/documentation_working_group_aka_dawgs.2022-05-10-15.01.log.html

[mariolenz]

I'm not sure if I'll find the time to join your meeting, but I thought that ansible-community/community-topics#91 might be interesting for you to discuss.

I've already started with community.vmware and the Guidelines for VMware module development are now available within the collection documentation.

[samccann]

2022-05-17

opening chatter

• https://github.com/ansible/community/issues/643#issuecomment-1122585506 --> agenda

Documentation updates

• • how much if any execution environment mentions do we want in Ansible docs?
• • we should at least mention in user guide and dev guide for collections

doctools

• https://ansible-builder.readthedocs.io/en/stable/definition/ is the basic one for defining EEs

splitting doctools into a separate channel

• we could split doctools to a separate channel to keep this one docs focused (words on paper)
• this would help new community writers, but this channel doesn't get a lot of doctools chatter except in meetings so may not be necessary

sample output for return values

• can we create a 'sample' output for return values in module docs? Got feedback that a fully-formed example would help people understand it better.
• the existing return value samples are per-key and not authored necessarily to be a consistent full example. The result of using this info could produce garbage

Open Floor

• https://github.com/ansible/ansible/pull/77719 <= refactoring, trying to make easier for others to use api to get sidecar info, also fixing some bugs

Actions

• [x] @samcann open issues for adding basic EE info to user and collection dev guides
• [x] @samccann to ask builder team about meta/execution-environment.yml

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-05-17/documentation_working_group_aka_dawgs.2022-05-17-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-05-17/documentation_working_group_aka_dawgs.2022-05-17-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-05-17/documentation_working_group_aka_dawgs.2022-05-17-15.00.log.html

[samccann]

Agenda - 2022-05-24

Documentation work

• [ ] review any docs-based action items from last week

ongoing work:

• [ ] proposing we archive docs for EOL releases - see https://github.com/ansible-community/community-topics/issues/78
• [ ] examples repo - call for examples! https://github.com/ansible-community/community-examples/
• [ ] New documentation issues and requests for help and the easyfix issues
  • [ ] moving more collection scenario guides. see community.general for it in action!
• [ ] Pending docs PRs that need help
  • [ ] Docs survey feedback issues - https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+survey (6)

Docs tooling (antsibull etc)

• [ ] Action Item review
• [ ] New items:
• [ ] Updates on ongoing work:
  • [ ] rendering docs in a collection PR (briantist's work) - https://github.com/ansible-community/github-docs-build and wiki - https://github.com/ansible-community/github-docs-build/wiki

Open Floor

[samccann]

2022-05-24

Documentation updates

• EOL for 2.9 and 2.10. Docs updates coming

Archive docsite

• will move older docsets to an archive site. At what point do we move more recent EOL docs over once it is set up? https://github.com/ansible-community/community-topics/issues/78#issuecomment-1072535541
• looking for feedback on when we can migrate EOL docs to a separate archive site to improve google search results

community writers

• • working on a community docs project board to coordinate across a group of volunteer community writers
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

Open Floor

• • left hand navigation/user guide TOC etc is long and confusing. Needs some improvements to make it more welcoming/easier to find info for new and experienced users

Actions

• [x] @samcann open an issue about user guide toc

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-05-24/documentation_working_group_aka_dawgs.2022-05-24-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-05-24/documentation_working_group_aka_dawgs.2022-05-24-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-05-24/documentation_working_group_aka_dawgs.2022-05-24-15.01.log.html

[samccann]

2022-05-31

Documentation updates

• Ansible 2.9 and 2.10 are officially EOL for community.
• need help - https://github.com/ansible/ansible/issues/77908 python package on RHEL/centos for kerberos.

community docs writers project

• • working on a community docs project board to coordinate across a group of volunteer community writers

Archive docsite

• will move older docsets to an archive site. At what point do we move more recent EOL docs over once it is set up? https://github.com/ansible-community/community-topics/issues/78#issuecomment-1072535541

doc-tools

• https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections
• https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections is a little buried- let's surface it better in the docs
• https://github.com/ansible-community/github-docs-build/wiki/Getting-started-with-GitHub-Pages
• some discussion about security 'worries' over github PR workflow proposed for collection docs changes https://meetbot.fedoraproject.org/ansible-windows/2022-05-24/ansible_windows_working_group.2022-05-24-20.00.html
• no specific vulnerabilities but probably not something to use on a RH based certified collection. Will be open for other community collections soonish

Open Floor

• pr review welcome on revamped Getting Started guide - https://github.com/ansible/ansible/pull/77897
• https://opensource.com/article/20/2/zuul

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-05-31/documentation_working_group_aka_dawgs.2022-05-31-15.02.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-05-31/documentation_working_group_aka_dawgs.2022-05-31-15.02.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-05-31/documentation_working_group_aka_dawgs.2022-05-31-15.02.log.html

[samccann]

2022-06-07

Documentation updates

• revamped getting started published! - https://docs.ansible.com/ansible/devel/getting_started/index.html
• need some reviews on these http redirects for the old getting started and quickstart guide pages - https://pastebin.com/iYCskNLD
• we have a set of redirects 2.9 <-> Ansible 3,4,5,(6). Do we need them around for Ansible 7 when 2.9 has already EOL'd?
• Seems like our redirects are either pre-2.5, or 2.9 <--> Ansible package (to support version switcher)
• but 2.9 is EOL and no longer in version switcher so may not need those redirects anymore.

Ansible community-writers

• we now have a batch of technical writers volunteering to help out with Ansible docs (across all projects)
• for now, this is limited to docs PR reviews and anything well-described in the issue that can be solved with Github Edit button.
• this is open to collection owners, any ansible-related project that needs help
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

doctools

• Do we want to add names to changlogs? See https://github.com/ansible/awx/releases/tag/21.1.0 (especially new contributors)

Actions

• [ ] @samccann - test out bringing back redirects for pre -2.5 (https://github.com/ansible/docsite/pull/38/files) and if that works, open community-topic to discuss if we bring that back but lose redirects 2.9 <--> Ansible package docs
• [x] @samccann to create issue to add to changelog fragment instructions that they should be written for end users unless the change is specific to a developer

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-06-07/documentation_working_group_aka_dawgs.2022-06-07-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-06-07/documentation_working_group_aka_dawgs.2022-06-07-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-06-07/documentation_working_group_aka_dawgs.2022-06-07-15.01.log.html

[samccann]

2022-06-14

Documentation updates

• revamped getting started published! - https://docs.ansible.com/ansible/devel/getting_started/index.html
• need reviews of redirects for traffic from old location to new. It's a private github repo (boo) but see this pastbin https://github.com/ansible-community/github-docs-buil

Ansible OS Docs on this week's Twitter Space!

• community-writers team is hosting a meeting on the Write the Docs NG twitter space this Friday, covering what is open source, docs, and how to use Ansible as an introduction to contributing to opensource projects
• https://twitter.com/NgDocs/status/1533785549806477312
• https://twitter.com/NgDocs/status/1533785549806477312
• To participate in the Twitter Space live, log in with your Twitter account and join https://twitter.com/i/spaces/1mrGmarvpdLGy on June 17 at 19:30 WAT/UTC +1
• The recording will be available after the event for 30 days

Docs updates again

• Ansible 6 goes out in a week so we're staging docs etc in preparation.
• plan going forward is to keep latest and devel docs in sync (aka backports). Wish us luck!
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.

doctools

• does ansible/ansible CI only test the core docs? We now have multiple rst pages that only exist in Ansible package docs and I worry we aren't getting CI testing on them anymore.
• might be time to update our requirements packages? sphinx/rstcheck are advancing, as is antsibull-docs, amongst others.

OpenFloor

• https://github.com/orgs/ansible-community/projects/3/views/1?layout=board

Actions

• [x] @samccann to get the new getting started guide in the bullhorn newsletter
• [x] @samccann open a community-topic to discuss docs and CI and how to get CI testing on excluded (aka package only) docs

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-06-14/documentation_working_group_aka_dawgs.2022-06-14-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-06-14/documentation_working_group_aka_dawgs.2022-06-14-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-06-14/documentation_working_group_aka_dawgs.2022-06-14-15.01.log.html

[samccann]

2022-06-21

Documentation updates

• Work beginning on revamping the user guide. See https://github.com/ansible/ansible/issues/78082#issuecomment-1159185553 for details on how we'll proceed.
• Ansible 6 will release today. Will take a bit to get docs in place and published to match but should happen today or tomorrow latest.
• WriteTheDocs NG hosted a session on Friday for Open Source docs and Ansible!
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.

doctools

• • we have canonical URL in Ansible 2.3 working as a PR. Will work to get it merged this week.
• Looking for ideas on how to get CI testing to work on rst pages excluded from ansible-core (what ansible/ansible CI covers today) - Please comment on https://github.com/ansible-community/community-topics/issues/111

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-06-21/documentation_working_group_aka_dawgs.2022-06-21-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-06-21/documentation_working_group_aka_dawgs.2022-06-21-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-06-21/documentation_working_group_aka_dawgs.2022-06-21-15.00.log.html

[samccann]

Meeting summary 06-28-2-22

opening chatter

Documentation updates

• Userguide getting a facelift! https://github.com/ansible/ansible/issues/78082#issuecomment-1159185553 (samccann, 15:05:23)
• LINK: https://github.com/ansible/ansible/pull/78097 (DonNaro[m], 15:08:54)
• LINK: https://github.com/ansible/ansible/pull/78099 (DonNaro[m], 15:09:01)
• LINK: https://github.com/ansible/ansible/pull/78103 (DonNaro[m], 15:09:08)
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board. (samccann, 15:18:48)
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs (samccann, 15:19:52)

doctools

• • Need reviews for canonical URL in Ansible 2.3 https://github.com/ansible/ansible/pull/78135 (samccann, 15:24:56)
• Do we need to back out the docs override for boolean values? - https://github.com/ansible-community/community-topics/issues/116 (samccann, 15:28:14)
• Looking for ideas on how to get CI testing to work on rst pages excluded from ansible-core (what ansible/ansible CI covers today) - Please comment on https://github.com/ansible-community/community-topics/issues/111 (samccann, 15:49:42)

Open Floor

[samccann]

2022-07-12

opening chatter

• https://github.com/ansible/community/issues/643#issuecomment-1168914269 is the agenda

doctools

• • Can we use redirects based on referrers to redirect old EOL docs to latest?
• Do we need to back out the docs override for boolean values? - https://github.com/ansible-community/community-topics/issues/116
• If YAML 1.2 doesn't recognise "yes" and "no", at some point down the line this is going to bite us

Docs Updates

• debating where the windows developer guides should be sourced - https://github.com/ansible-collections/community.windows/issues/394 and https://github.com/ansible/community/issues/643#issuecomment-1180358267

Actions

• [x] @samccann to test one redirect based on referrer for 2.3 and see how it works.
• [x] @samccann to view 2.3 docs to see how many are not 1x1 match with latest
• [ ] @- samccann to back out the docs override for boolean

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-07-12/documentation_working_group_aka_dawgs.2022-07-12-15.02.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-07-12/documentation_working_group_aka_dawgs.2022-07-12-15.02.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-07-12/documentation_working_group_aka_dawgs.2022-07-12-15.02.log.html

[briantist]

• https://github.com/ansible-collections/community.windows/issues/394#issue-1228299886

We discussed this briefly during the last WWG (https://github.com/ansible/community/issues/644#issuecomment-1173906302) and I think there's consensus on that side for ansible.windows being a more appropriate place than community.windows. Any concerns with that from the docs side?

Docs build workflows have been enabled on community.windows, and there's an open PR for that on ansible.windows too (https://github.com/ansible-collections/ansible.windows/pull/388).

If the WWG and DaWGs folks all agree on a destination, I can put up a PR for making that guide part of one of the collections.

I will be AFK all day for the 7/12 UTC meeting but I will see comments on linked issues and can view the meeting minutes if necessary.

cc @nitzmahone @jborean93

[mariolenz]

@briantist

• Migrate Windows module development guide to this collection ansible-collections/community.windows#394 (comment)

We discussed this briefly during the last WWG (#644 (comment)) and I think there's consensus on that side for ansible.windows being a more appropriate place than community.windows. Any concerns with that from the docs side?

I don't see myself as part of "the docs side", but I think the important thing is to move the Windows module development guide out of ansible-core. If you prefer ansible.windows over community.windows, that should be OK.

cc @samccann

[briantist]

@briantist

• Migrate Windows module development guide to this collection ansible-collections/community.windows#394 (comment)

We discussed this briefly during the last WWG (#644 (comment)) and I think there's consensus on that side for ansible.windows being a more appropriate place than community.windows. Any concerns with that from the docs side?

I don't see myself as part of "the docs side", but I think the important thing is to move the Windows module development guide out of ansible-core. If you prefer ansible.windows over community.windows, that should be OK.

cc @samccann

@mariolenz There was some brief chatting with @samccann in the channel today; personally I'm not sure it should even move out of core since much of the required machinery (from internals to module_utils [here, and here]) is still in core. But I think it's more up to core members to weigh in on that. If consensus is that it should move, then imo ansible.windows makes more sense, but that's based mostly on it being "closer" to core.

It's also worth noting that Windows development is not limited to the two existing Windows collections (one of which has stopped accepting new content); developing Windows modules is on par with the development guide for Python modules (if we're moving that guide too, then I guess it's more consistent to move this one as well).

[jborean93]

It's a bit of a tricky one. A lot of the docs in there are really collection agnostic and any collection can write Windows modules. As @briantist mentioned it references Ansible.Basic.cs which is still a module util inside of the Ansible repo itself so we can technically run the risk of it not staying in sync. It's not the end of the world that it moves but it is technically generic info for Ansible rather than something specific to that collection.

[felixfontein]

I think the generic stuff, especially what's covering ansible-core's module_utils, should stay in the ansible-core repository. This should also be part of ansible-core's documentation. If there is anything specific to ansible.windows and/or community.windows, that should go into the collections (I didn't see anything though, but then I also didn't look very closely :) ).

[samccann]

2022-07-19

Documentation Updates

• https://github.com/ansible-collections/community.windows/issues/394 and https://github.com/ansible/community/issues/643#issuecomment-1180358267
• :+1: do not move the windows developer guide to a collection. It's more generic and belongs where it is
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.

doctools

• • redirects based on referrers to redirect old EOL docs to latest seem to work - https://hackmd.io/0B7n-FUySF6MB3CQeaqUkA?view
• this may solve our problems with external search results picking up very old EOL docs within the top few results
• Looking for ideas on how to get CI testing to work on rst pages excluded from ansible-core (what ansible/ansible CI covers today) - Please comment on https://github.com/ansible-community/community-topics/issues/111
• https://github.com/ansible/ansible/pull/36901/files#diff-b084faabfc6d6ec38de3459882739152a10e5173d5754e50db49ee423afa38eaR110
• for the docs boolean 'override' - it's not an override - there is no 'default' that the cooder meant. There's only the boolean indication in the code and docs has to decide whether it says true, True, or yes.
• must wait for resolution to https://github.com/ansible-community/community-topics/issues/116 before we make any changes.

Open Floor

• YAML 1.2 requires true/false but ansible is still on 1.1 and pyyaml hasn't implemented YAML 1.2 for the past 4 yrs or so

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-07-19/documentation_working_group_aka_dawgs.2022-07-19-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-07-19/documentation_working_group_aka_dawgs.2022-07-19-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-07-19/documentation_working_group_aka_dawgs.2022-07-19-15.00.log.html

[samccann]

2022-07-26

Documentation updates

• User guide is being split into multiple guides. See https://docs.ansible.com/ansible/devel/index.html for current status. More to come.
• • 2.3 docs audit - most pages 1x1 map to latest. See https://hackmd.io/0B7n-FUySF6MB3CQeaqUkA#23-Audit for details.
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.

DocTools

• boolean yes/no vs true/false etc vote happening at https://github.com/ansible-community/community-topics/issues/116 . Get your vote in before 8/03.
• both of the windows collections (community.windows and ansible.windows) are now using the github-docs-build tooling
• for https://github.com/ansible/ansible/pull/77719#issuecomment-1195253853 - filter docs don't work for ansible-doc --type filter --listandansible-doc --metadata-dump` or on the docsite
• most filters work, but some do not

Actions

• [x] @samccann to try RewriteCond %{HTTP_REFERER} ^. for referrer problem with 2.3

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-07-26/documentation_working_group_aka_dawgs.2022-07-26-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-07-26/documentation_working_group_aka_dawgs.2022-07-26-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-07-26/documentation_working_group_aka_dawgs.2022-07-26-15.00.log.html

[samccann]

2022-08-02

Documentation Updates

• accessibility guidelines we should investigate - https://www.ibm.com/able/
• we are down to 43 docs PRs, 13 docs-only, and 76 docs issues
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.
• browser back button doesn't seem to work well with version switcher of late.
• it's possible one of the js dependencies changed?
• https://github.com/ansible/ansible/blob/devel/test/sanity/code-smell/docs-build.requirements.txt
• http://web.archive.org/web/20220000000000*/docs.ansible.com

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-08-02/documentation_working_group_aka_dawgs.2022-08-02-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-08-02/documentation_working_group_aka_dawgs.2022-08-02-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-08-02/documentation_working_group_aka_dawgs.2022-08-02-15.01.log.html

[briantist]

Did something change with docs recently to make the version switcher no longer result in a new page navigation? When I change versions now, I can no longer use the browser back and forward buttons to get back to the version I was on. This is particularly bad for going to 2.9 docs where the version switcher disappears, so I have to edit the URL to go back to where I was.

[samccann]

2022-08-09

Documentation updates

• PR to set the managed node requirements needs tech review - https://github.com/ansible/ansible/pull/78468
• User guide is being split into multiple guides. See https://docs.ansible.com/ansible/devel/index.html for current status. More to come.
• https://docs.ansible.com/ansible/latest/network/getting_started/network_differences.html#execution-on-the-control-node
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.
• always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

doctools

• Switching boolean yes/no vs true/false based on https://github.com/ansible-community/community-topics/issues/116.
• need to update docs requirements before end of core freeze (aka by early Sept).

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-08-09/documentation_working_group_aka_dawgs.2022-08-09-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-08-09/documentation_working_group_aka_dawgs.2022-08-09-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-08-09/documentation_working_group_aka_dawgs.2022-08-09-15.00.log.html

[samccann]

2022-08-16

Booleans

• antsibull-docs fix for true/false booleans has been merged - https://github.com/ansible-community/antsibull-docs/pull/19
• https://github.com/ansible/ansible/pull/78557 changes ansible-doc output as well for true/false
• https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/doc.py#L1098
• https://github.com/ansible/ansible/blob/devel/lib/ansible/cli/doc.py#L1144 <= if we remove the excceptions, this should do all the work
• the ansible/ansible 'fix' is to remove the current python stringification and let yaml do it

Documentation Updates

• Starting a new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
• This is specific to docs in the ansible/ansible repository and triages incoming issues into those categories. Feedback welcome on the design and if you disagree with any of the priority settings etc

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-08-16/documentation_working_group_aka_dawgs.2022-08-16-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-08-16/documentation_working_group_aka_dawgs.2022-08-16-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-08-16/documentation_working_group_aka_dawgs.2022-08-16-15.00.log.html

[samccann]

2022-08-23

Docs Updates

• archiving 2.3 docs hopefully this week. They will be available from docs.ansible.com/archive.
• Reminder on new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
• Help on issues always welcome :-)
• User guide is being split into multiple guides. See https://docs.ansible.com/ansible/devel/index.html for current status. More to come.
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.

doc tools updates

• docs warnings down from 1.1K to 174 thanks to antsibull-docs update!
• this will not be part of the docs requirements until early September, so you'll have to manually update antsibull-docs >= 1.3 to get this locally
• Switching boolean yes/no vs true/false based on https://github.com/ansible-community/community-topics/issues/116.
• https://github.com/ansible/ansible/pull/78561 - right now there are syntax errors that need to be fixed
• the remainder of boolean work involves the WIP PR https://github.com/ansible/ansible/pull/78561 for core, and manually changing collection examples in each collection

Open Floor

• https://github.com/ansible-community/antsibull-docs/issues/ currently has zero open issues ;)

Actions

• [x] @samccann to open discussion on when we can get CI container updates for 2.14 (esp if it has to happen after branch pull due to late changes in sidecar docs-related feature
• [ ] @sammcann to nag about https://github.com/ansible/ansible/pull/78561 status
• [ ] @samccann to open an issue 'somewhere' to track all the collections that should consider using true/false boolean in examples (tho some may not want to for $REASONS)
• [x] @samccann to followup with whether boolean examples MUST or SHOULD be true/false in collection inclusion criteria

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-08-23/documentation_working_group_aka_dawgs.2022-08-23-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-08-23/documentation_working_group_aka_dawgs.2022-08-23-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-08-23/documentation_working_group_aka_dawgs.2022-08-23-15.01.log.html

[samccann]

2022-08-30

Action Item updates:

• resolved - Collectionw SHOULD use boolean true/false in examples. (aka it's not a MUST)
• open - Create tracking issue 'somewhere' to track all the collections that SHOULD consider using true/false boolean in examples (tho some may not want to for $REASONS)
• open - if https://github.com/ansible/ansible/pull/78561 will be completed by 2.14 freeze (booleans in ansible-doc output).
• resolved - the remaining sidecar docs work should be completed this week, so we should be okay to get CI updated to use the most recent antsibull-docs versions soon (before 2.14 branch pull)

Documentation updates

• archiving 2.3 docs -waiting on Jenkins help to define the output path. They will be available from docs.ansible.com/archive.
• Reminder on new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
• Help on issues always welcome :-)
• Reminder on new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
• Help on issues always welcome :-)
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.

doctools

• including collection-level changelogs into docs.ansible.com - https://github.com/ansible-collections/community.hashi_vault/pull/299
• with example output at https://ansible-collections.github.io/community.hashi_vault/pr/299/collections/community/hashi_vault/index.html

Actions

• [ ] @samccann create WIP PR to update docs CI test requirements ready for merging aorund Sept 12

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-08-30/documentation_working_group_aka_dawgs.2022-08-30-15.02.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-08-30/documentation_working_group_aka_dawgs.2022-08-30-15.02.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-08-30/documentation_working_group_aka_dawgs.2022-08-30-15.02.log.html

[briantist]

I would like to get feedback on this idea I had about publishing my collection's changelog in the docsite, and whether we might want to consider first class support for it in the tooling (maybe an entry in links.yml to control it), that would make it easier to opt-in and avoid the need for a symlink.

More info here:

• https://github.com/ansible-collections/community.hashi_vault/pull/299

Rendered example:

• https://ansible-collections.github.io/community.hashi_vault/pr/299/collections/community/hashi_vault/index.html

[samccann]

2022-09-13

Action Item updates:

• core freeze is Sept 19
• resolved action item - https://github.com/ansible/ansible/pull/78668

Core Freeze

• items to complete before core freeze:
• update docs build dependencies (keeping rstcheck < 6 for now)
• merge of https://github.com/ansible/ansible/pull/78700 so new filter/test plugins display correctly
• possible update to antsibull-docs based on results of ansible/ansible#78700
• would be good to have more filter docs as there aren't many yet with the new sidecar docs feature in 2.14
• https://github.com/ansible/ansible/pull/78548
• open action item - Create tracking issue 'somewhere' to track all the collections that SHOULD consider using true/false boolean in examples (tho some may not want to for $REASONS)
• https://github.com/ansible/ansible/issues/78760

Documentation updates

• archiving 2.3 docs archive is at https://docs.ansible.com/archive/ansible/2.3/. Redirects coming soon for older urls .
• User guide high-level restructure complete - https://docs.ansible.com/ansible-core/devel/index.html Feedback welcome
• Reminder on new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
• Help on issues always welcome :-)
• • if you need an editor to review docs PRs or do light editing (edit on github) we have a team of community writers willing to help. See https://github.com/orgs/ansible-community/projects/3/views/1?sortedBy%5Bdirection%5D=asc&sortedBy%5BcolumnId%5D=Status and ping us here if you need access to add your PRs/easyfix issues to that board.

doctools

• nightly docs build broken still.
• https://galaxy.ansible.com/community/aws

Open Floor

• https://github.com/ansible-collections/community.hashi_vault/#collection-documentation

Actions

• [x] @samccann to clarify w bcoca on whether he is omitting filter docs from https://github.com/ansible/ansible/pull/78548 in his filter docs PR
• [x] @samccann to discuss requirements update w/ matt due to broken docs build etc
• [x] @samccann to get PR for requirements update ready
• [x] @samccann to open issues on community.aws, community.windows, and possibly ansible.windows on using the correct links to module-level docs
• [x] @samcann also review amazon.aws for similar issue

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-09-13/documentation_working_group_aka_dawgs.2022-09-13-15.01.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-09-13/documentation_working_group_aka_dawgs.2022-09-13-15.01.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-09-13/documentation_working_group_aka_dawgs.2022-09-13-15.01.log.html

[samccann]

2022-09-20

Action Item updates:

• open - Create tracking issue 'somewhere' to track all the collections that SHOULD consider using true/false boolean in examples (tho some may not want to for $REASONS)
• resolved - merged antsibull-docs update to docs requirements. Will need to schedule remaining requirements updates for later this Autumn
• resolved - collection owners fixed a few broken docs links in their Galaxy docsite links etc

Hacktoberfest

• we hope to participate in Hactoberfest by creating a batch of easy-fix issues to help us clean up the docs. See https://hacktoberfest.com/participation/ for what this is
• initial brainstorming ideas of what we could fix - https://hackmd.io/gNQ2TQW8T4ilcZc8JAM5fQ
• should also consider some repos won't want to participate in hacktoberfest as it does trigger some 'spam' PRs.

Documentation updates

• https://github.com/ansible-collections/community.hashi_vault/pull/299
• https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/index.html#changelog
• IF we have more markup languages for docs in other projects, they must have a reasonable display on github
• any markup has to also display well on docs.ansible.com as a priority
• one option - we could recommend RST for ansible projects, but allow MD if it already exists, etc.

Open Floor

• generally leaning toward 'recommending RST but allowing MD
• consider it as a possible optional separate DaWGs meeting

Actions

• [x] @samccann to ask community team if someone has rights to add hacktoberfest topic to all collections (esp new ones as this was done last year for existing collections)
• [x] @samccann to open issue(s) to suggest collection owners link in their changelogs (such as https://github.com/ansible-collections/community.hashi_vault/pull/299)
• [ ] @samccann to consider an 'open docs hr' later in the week to regularly interact with docs contributors in a friendlier way than the expert details that happen in DaWGs meetings
• [ ] @samccann -t to add a link to a separate intro to the agenda for welcome/here's what you need to know/ etc so newcomers can prepare.

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-09-20/documentation_working_group_aka_dawgs.2022-09-20-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-09-20/documentation_working_group_aka_dawgs.2022-09-20-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-09-20/documentation_working_group_aka_dawgs.2022-09-20-15.00.log.html

[samccann]

2022-09-27

Action Item updates:

• resolved - Create tracking issue https://github.com/ansible-community/community-team/issues/60 to track all the collections that SHOULD consider using true/false boolean in examples and also opened https://github.com/ansible-community/community-team/issues/61 to suggest adding changelogs to the collection rst fun.
• open - Consider an 'open docs hr' later in the week to regularly interact with docs contributors in a friendlier way than the expert details that happen in DaWGs meetings
• open add a link to a separate intro to the agenda for welcome/here's what you need to know/ etc so newcomers can prepare.

Hacktoberfest

• it's coming up in 1 week. What issues should we try to tackle with hactoberfest volunteers? Some ideas - https://hackmd.io/gNQ2TQW8T4ilcZc8JAM5fQ

Documentation updates

• Ansible 7 alpha coming soon. When do we want to start staging docs on test?
• archiving 2.3 docs archive hit a snag with redirects. No simple way to redirect all the modules to collections.
• Reminder on new project tracking board for Ansible docs- https://github.com/orgs/ansible/projects/94
• Help on issues always welcome :-)

doctools

• antsibull-docs fixes to consider - https://github.com/ansible-community/antsibull-docs/issues/38 and https://github.com/ansible-community/antsibull-docs/pull/43

Actions

• [x] @samccann start weekly staging of core and Ansible docs to test and ping here for folks to review etc.
• [x] @samccann to remove subdirs from toshio's batch of 2.9 <---> latest redirects to fix 2.3 redirect problems for EOL docs

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2022-09-27/documentation_working_group_aka_dawgs.2022-09-27-15.00.html Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2022-09-27/documentation_working_group_aka_dawgs.2022-09-27-15.00.txt Log: https://meetbot.fedoraproject.org/ansible-docs/2022-09-27/documentation_working_group_aka_dawgs.2022-09-27-15.00.log.html

[felixfontein]

• [x] https://github.com/ansible-community/antsibull-docs/issues/38 / https://github.com/ansible-community/antsibull-docs/pull/42 /

[felixfontein]

• [x] https://github.com/ansible-community/antsibull-docs/pull/43