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-01-25

Documentation updates

• start of splitting community guides - https://docs.ansible.com/ansible/devel/index.html
• follow this topic to discuss this - Revamping the community/contributor documentation ansible-community/community-topics#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 FEEDBACK WANTED: Crafting better changelog fragments ansible-community/community-topics#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

• docs - lookup guide ansible-collections/community.hashi_vault#211

Actions

• @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 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-build#355
• to see this in action - https://ansible.fontein.de/collections/community/dns/
• Improve attributes table PR - Improve attributes table ansible-community/antsibull-build#401 looks good!
• Use docs/docsite/links.yml file to create extra links ansible-community/antsibull-build#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-build#401

[samccann]

2022-02-22

doctools

• Use docs/docsite/links.yml file to create extra links ansible-community/antsibull-build#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-build#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