DaWGs (Documentation Working Group) Meeting Agenda 2022

[samccann]

This agenda is old. The new agenda for 2023 is at #678

[samccann]

2022-01-04

opening chatter

• new agenda issue for the new year! DaWGs (Documentation Working Group) Meeting Agenda 2022 #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
• Docs survey feedback: add a "cheatsheet" for the main commands ansible-documentation#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

• @@samccann to push more on the semantic markup review internally and include the example links
• @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 - Expand test ansible#75695
• @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

• @@samccann to turn community docs idea into a community-topic proposal and share on bullorn and reddit
• @@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 - Create separate core vs collection contributor guides ansible#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

• @samccann to change room alert to 31 hrs for help wanted nag
• @felixfontein to write up an addition to the semantic markup to support seealso: for plugins as well as modules
• @samcann acozine - to review Confusing ansible-test cli help ansible#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-02-01

opening chatter

• Agenda DaWGs (Documentation Working Group) Meeting Agenda 2022 #643 (comment)

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
• Canonical url rendering on docs ansible#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)
• accessibility feedback on module tables ansible-community/antsibull-docs#66
• 0.40.1 -> 0.40.2 fixes broken HTML - accessibility feedback on module tables ansible-community/antsibull-docs#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 (Improving Docker modules #379)."
• 0.40 to 0.40.1 - https://github.com/ansible-community/antsibull/releases/tag/0.40.1
• Use antsibull 0.40.1 for docsite build ansible#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: build-init - lenient, fail-on-error, antsibull-version ansible-community/github-docs-build#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): The shared workflows reference actions as though they are external rather than in the same repository ansible-community/github-docs-build#4 (comment)

Actions

• @samccann to book time with search expert to help us reduce search results to ancient docs
• @samccann gunalow - get his cannonical url for 2.3 work staged on test etc
• @gundalow to look if redirects are broken
• @samccann to test Bump antsibull version from 0.40.1 to 0.41.0 and ansible sphinx theme version to fix HTML generation in return value tables ansible#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 - Fix some favicon issues ansible-community/sphinx_ansible_theme#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 - Use docs/docsite/links.yml file to create extra links ansible-community/antsibull#355
• to see this in action - https://ansible.fontein.de/collections/community/dns/
• Improve attributes table PR - Improve attributes table ansible-community/antsibull#401 looks good!
• Use docs/docsite/links.yml file to create extra links ansible-community/antsibull#355

open Floor

• documenting to_seconds filter ansible-collections/community.general#4203 <= example documenting filter that is in 'multifilter file'
• https://github.com/ansible-collections/community.general <= example documenting filter that is in single file
• Add docs for ansible-core 2.13 use ansible-collections/community.general#4202 sorr, that one

Actions

• @samccann to investigate an instruqt tutorial on contributing to docs
• @samccann to open community-topic to debate community guides on devel only or regular backports to latest etc
• @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]

• Improve attributes table ansible-community/antsibull#401

[samccann]

2022-02-22

doctools

• Use docs/docsite/links.yml file to create extra links ansible-community/antsibull#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) - unversioning some documentation guides ansible-community/community-topics#68 Please add your comments there.

documentation Updates

• crafting better changelog fragments PR - ttps://github.com/update changelog fragment guidance with examples ansible#77040

Actions

• @samccann to have a PR for how to edit collection docs once Use docs/docsite/links.yml file to create extra links ansible-community/antsibull#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) - unversioning some documentation guides ansible-community/community-topics#68 Please add your comments there.
• adding extra links to collection and module docs pages - Use docs/docsite/links.yml file to create extra links ansible-community/antsibull#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

• @samccann to ping individuals not here about DST time shift for the meeting
• @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]

• 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
• Documentation: you changed URLs but are not using redirects, generating 404s - why? ansible#77204
• redirect removed by allow /ansible/3/ as a pattern, remove general redirect docsite#38
• the relevant diffs - https://pastebin.com/kMvgKFLJ

doctools

• looking for help on Update environment variables page to also include plugins ansible-documentation#144. Likely requires coding but not even sure where
• take a look at Use docs/docsite/links.yml file to create extra links ansible-community/antsibull#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

• @samccann to ask webserver folks for access logs to see how often these old urls are used
• @samccann to check web analytics for these older unversioned urls
• @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 - Use docs/docsite/links.yml file to create extra links ansible-community/antsibull#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 Confusing ansible-test cli help ansible#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 - Ansible community documentation priorities ansible-community/community-topics#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 - Ansible docs install trimmed down to 'pip' ansible-community/community-topics#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 - unversioning some documentation guides ansible-community/community-topics#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

• Most Matrix channels are ansible.com and not .im ansible#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]

Dec 12 2022 Meeting Minutes

Action item updates

open - oraNod - to look into getting community maintainer(s) for the sphinx ansible theme

open - samccann flesh out the personas by completing the todo items and putting them in a detailed slidedeck that describes each.

Documentation updates

• Looking for feedback on how to open up the docs publishing pipeline - Opening up the docs.ansible publishing process ansible-community/community-topics#174

• must document how this works as well as have logging/tracking of who or what published the docs and when.

• Also looking for feedback/ideas on user experience improvements for the Ansible docsite - Mapping user journeys for the Ansible docsite ansible-community/community-topics#175

• site search still lacking. Many people avoid it because the results they want show up on page 2 or later. Need facets. And a full docs.ansible.com site search.

• need more step by step content. End to end tutorial from ansible -m ping to a butch of stuff like tags, strategies, changed_when and failed_when

• Can revamp/modernize this self-annotated playbook example and include links to the docs from each item - https://github.com/phred/ansible-examples/blob/master/pedantically_commented_playbook.yml

Action Items

• samccann to ask about options for a persona-based doc survey
• samccann to ask on user channel - what sorts of items get asked about time and again that we could answer in docs
• oranod - to share the community-topics for docs in the user, community, and dev channels for feedback

mccann to ask on user channel - what sorts of items get asked about time and again that we could answer in docs

[felixfontein]

• Callback plugins: show type, render indexes of callback plugins per type ansible-community/antsibull-docs#90