DaWGs (Documentation Working Group) Meeting Agenda 2023

[samccann]

NOTE - The Agenda is now tracked at https://forum.ansible.com/t/documentation-working-group-agenda/153/7
Meeting minutes are now at https://forum.ansible.com/tags/c/workflow/meetbot/16/documentation

This tracks the DaWGs (Documentation Working Group) meetings for Ansible docs, starting from Jan. 2023.

This team uses the Ansible Documentation project tracking board.

If you have a question, comment, idea, or anything else to discuss, please leave a comment here to add it to the agenda for our next meeting. If you don't show up for the meeting, your item will probably be skipped.

If your matrix or nick is different from your Github username, leave that as well.

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

Once an item has been addressed please edit the text to make it strike-through style (two tildes ~~ on either side of the text) or check the checkbox if available.

When creating new agenda ensure docs and meeting_agenda labels are set.

Join us anytime in #docs on matrix or #ansible-docs on libera IRC!

See ansible/ansible#643 for 2022 minutes

[samccann]

2023-01-03

Action Item updates:

• open - oraNod - to look into getting community maintainer(s) for the sphinx ansible theme
• https://github.com/ansible-community/community-team/issues/
• open - samccann flesh out the personas by completing the todo items and putting them in a detailed slidedeck that describes each.
• open ansible/ansible docs issue to add links to the new collection envvar index page after the next antsibull-docs release
• feedback wanted on Callback plugins: show type, render indexes of callback plugins per type ansible-community/antsibull-docs#90

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

Actions

• @samccann to change ...something... so autobot messages on docs issues point to new agenda.
• write up what the different types of callback mean. aka notification was supposed to be for callbacks that 'notify other systems/apps/apis' while aggregate are those that add info to sdtout one
• @samccann dnaro - to figure out a discussion or two for Contrib summit on personas and docsite revamp

Logs

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

[samccann]

2023-01-10

Action Item updates:

• open - oraNod - to look into getting community maintainer(s) for the sphinx ansible theme
• open samccann to finalize personas for community review
• open Write up what the different types of callback mean. aka notification was supposed to be for callbacks that 'notify other systems/apps/apis' while aggregate are those that add info to sdtout one
• open samccann dnaro - to figure out a discussion or two for Contrib summit on personas and docsite revamp
• for the sphinx ansible theme I plan to send a shout on the bullhorn to call for community contributors. I thought I'd wait until this week.
• closed ansible/ansible docs issue to add links to the new collection envvar index page after the next antsibull-docs release
• docsite: bump antsibull-docs, reference collection env var index ansible#79666

community-writers

• for community-writers engagement - consider positng contrats on twitter/linked in to the contributor with the highest merged PR count
• in general, find ways to extend the visibility of these community-writers as a way to help further their careers for the work they are doing in Ansibleland
• https://www.youtube.com/@AnsibleCommunity

Open Floor

• the package docs publishing action topic at: Opening up the docs.ansible publishing process ansible-community/community-topics#174
• I set �CPUS=1 which helped the build get a bit farther. it does all the collections docs but still seems to be running out of steam.
• plan now is to investigate a self-hosted runner. I looked at a jenkins webhook earlier today, which is ok but kind of a half-baked solution for the community imo.

Actions

• @SamCann to search for writer reqs at Red Had and post links on discord

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2023-01-10/documentation_working_group_aka_dawgs.2023-01-10-16.01.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2023-01-10/documentation_working_group_aka_dawgs.2023-01-10-16.01.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2023-01-10/documentation_working_group_aka_dawgs.2023-01-10-16.01.log.html

[samccann]

Jan 17 2023 Meeting Minutes

Action Items

• closed - flesh out the personas by completing the todo items and putting them in a detailed slidedeck that describes each
• open samccann dnaro - to figure out a discussion or two for Contrib summit on personas and docsite revamp
• closed samccann to search for writer reqs at Red Had and post links on discord

Documentation updates

• will likely archive the examples repo as it never got any traction - https://github.com/ansible-community/community-examples/
• Original purpose was to help users learn by example for how to filter with jinja2 etc but never got traction
• Post your feedback on this at TODO ansible-community/community-examples#2 (comment)

Personas

• community personas available for review at https://hackmd.io/KJInEFJmRfWsFGBGxEzviw?both
• docsite personas (subset of these) available for review at https://hackmd.io/pZb5w5JFRQW3RJ73n23tlw?both#. Post comments in the community-topic at Mapping user journeys for the Ansible docsite ansible-community/community-topics#175
• the reason oraNod created the docsite personas is to have a stab at identifying the main entry points for users on docs.ansible and then mapping out workflows / journeys and ensuring content is there to support them along their paths

Open Floor

• Feedback wanted on proposal to open up docs publishing to community members. See prototype at https://github.com/oraNod/docsite/actions/runs/3929877123/jobs/6719204771

Action item review

• samccann to simplify community personas and create community-topic to discuss (post in bullhorn etc)
• oraNod to create a simple docsite demo that is based on the docsite personas so we can get feedback on that idea

[samccann]

DaWGs Meeting Minutes Jan 24 2023

Action Item updates

• open -Looking for community maintainer(s) for the sphinx ansible theme
• closed oranod to simplify community personas and create community-topic to discuss (post in bullhorn etc)
• closed oraNod to create a simple docsite demo that is based on the docsite personas so we can get feedback on that idea
• open samccann dnaro - to figure out a discussion or two for Contrib summit on personas and docsite revamp

Personas and docsite redesign

• feedback wanted at Mapping user journeys for the Ansible docsite ansible-community/community-topics#175

• next step on docsite redesign is to get the reader journeys mapped out and have an overall docs 2023 plan/roadmap

• need to include things like devtools docsite and GalaxyNG

Devtools docsite

• a WIP/experiment to gather all devtools docs under one site - https://ansible-devtools.readthedocs.io/

Open Floor

• waiting on core team approval to mark some plugins private - Allow to mark plugins in collections as private ansible#79370

• When that's done we can bump antsibull-docs to support it - docsite: bump antsibull-docs, reference collection env var index ansible#79666

• reminder - we need all docs requirements updated by end of Feb to make it in before core branch pull

• implemented 2.5 redirects so all hits to the old 2.5 docs go to latest now. Go to archive site if you need 2.5 (https://docs.ansible.com/ansible-prior-versions.html). next up - 2.6

Action Items

• samccann to summarize feedback here and pass it on to devtools team. Also ask what their goals are for this site
• samccann to verify who can be given ops rights in docs irc channel and get a few people added so we can reinvite zodbot when it goes on holiday
• samccann to see status of marking some plugins as private - Allow to mark plugins in collections as private ansible#79370 (waiting on core approval)

[oraNod]

2023-07-11

Moving docs out of ansible/ansible

• All seems ready to move forward with docs in the new repo.
• https://hackmd.io/c9SEj2FaRvKF5UhXNl9NtA#To-do-before-split
• to maintain technical stewardship of the docs, the core team will add any PRs that need docs to a new project board and the docs folks will convert that to an issue in the new repo
• we will also add a label of �techreview to docs PRs where we need someone technical to come in and review the change before we merge
• Review process for technical stewardship ansible-documentation#36
• we've also described some techniques/strategies to try and help reduce contributor overhead
• will inform core they can nuke the /docs folder in ansible/ansible

EE getting started and home for Ecosystem docs

• do we want a separate repo for ecosystem docs like the EE getting started? (docs that cover more than one project...
• Add EE docs ansible-documentation#18 (comment)
• 👍 we will not have a separate docs repo for ecosystem docs for now (like the EE getting started guide). Adds too much complexity

Documentation Updates

• awx operator work continuing for docs
• Shout out to sutapa_bhattacharjee for getting the mkdocs scaffolding ready! that was a big step forward
• and another shoutout to 0xanon.eth
  for setting the strategy and leading the effort to convert the big ol readme into a series of docs files!

Open Floor

• Remove the oldsite toggle jinja-docsite#122
• I've sent a PR to remove the oldsite toggle as agreed at the meeting before last
• Updates jinja templates for docsite pages jinja-docsite#130
• last week I went through all the issues and rewrote the jinja templates to fully separate the data from the html. so now, to add core translations for example, you'd only need to add a few new fields to the yaml files in the �data folder

Logs

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

[samccann]

2023-07-18

Ansible 8.2.0 release

• we have a gotcha to work through where the autogenerated porting guide for Ansible 8.2.0 is't picking up the core porting guide content.
• the ansible porting guide pulls in the core porting guide but isn't doing it for this release since the core porting guide moved to the new docs repo. We can manually patch around that for today's release
• draft announcement for the release https://hackmd.io/rKWD9mXyRGKOEhHU-drX1g?both

documentation updates

• EE getting started guide published to devel and work continuing on it
• awx operator work has a batch of PRs but each needs a rebase before/after a merge cuz they all touch the same area.
• proposed new scenario guide structure - Create galaxy_collection scenario guide ansible-community/community-team#310

Open Floor

• Set labelling strategy ansible-documentation#101

labelling strategy in new docs repo

• we have backport labels now that will automatically create backports to each stable branch, if labeled.
• other proposed label - �triage for new issues and PRs so we can ensure someone does an initial review of incoming items
• Add Github Action to label issues and PRs ansible-documentation#118
• Create autoresponder for docs PRs ansible-documentation#69
• Make order of options from argument_specs.yml configurable ansible-community/community-topics#253

Logs

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

[samccann]

2023-07-25

Preferred Terminology

• adding project terms to style guide - Update style guide with preferred terminology ansible-documentation#152.

Labelling strategy

• setting up labels in the docs repo - Set labelling strategy ansible-documentation#101

autoresponder

• in the old repo, we had a bot that would post links to matrix and the WG meeting minutes for every opened docs issue - Create autoresponder for docs PRs ansible-documentation#69

Trimming down galaxy guides

• galaxyNG becomes galaxy... sometime soonish? What do we do with existing Galaxy guides?
• this PR removes the duplicate collection details from the galaxy guide - update galaxy guide to link to collection guide ansible-documentation#145
• https://docs.ansible.com/ansible/devel/galaxy/user_guide.html#finding-roles-on-galaxy
• https://docs.ansible.com/ansible/devel/playbook_guide/playbooks_reuse_roles.html#sharing-roles-ansible-galaxy

docs tooling and docsite

• Add nox config to automate building docs ansible-documentation#54

Open Floor

• reminder to those on matrix - this room will close and a new room 'open' to fix a pending deprecation issue between matrix and the irc/discord bridge. You should see a link to the new room here when that happens

Actions

• @gotmax23 to update the ansible-documentation labeling workflow to add �new contributors labels and autoresponder for issues and PRs opened by new contributors

Logs

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

[samccann]

2023-08-01

Preferred Terminology

• adding project terms to style guide - Update style guide with preferred terminology ansible-documentation#152.
• proposal is to stop calling execution environments EE as shorthand.
• Should we ask other projects to adopt this terminology list?

Labeling Strategy

• how do we label non-docs issues? Set labelling strategy ansible-documentation#101 (comment)
• alternately, we can label all docs issues with the existing documentation label

Documentation updates

• we have 42 open issues and 15 open PRs

[samccann]

2023-08-08

Documentation Updates

• we have 40 open issues and 16 open PRs
• awx operator docs nearly there! just need to set up readthedocs and we can publish!

ansible-documentation release tagging

• Create tagged releases for stable branches ansible-documentation#66

Preferred terminology

• adding project terms to style guide - Update style guide with preferred terminology ansible-documentation#152.

Github metrics

• do we want to turn on metrics ? see https://github.blog/2023-07-19-metrics-for-issues-pull-requests-and-discussions/

Open Floor

• https://github.blog/2023-07-19-metrics-for-issues-pull-requests-and-discussions/

Logs

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

[samccann]

Documentation Working Group (DaWGs) 2023-08-15 Meeting Summary

Info Items

• we're trying the draft Matrix meeting bot this week. Commands are ^info and ^action. Only works from Matrix right now.
• will eventually log to the forum once it's active.
• awx operator RTD is nearly there! This was a community-writer project and we are nearly at the point of publishing it!
• kickstarting a community effort to create docs for the new galaxy collection Create galaxy_collection scenario guide ansible-community/community-team#310
• porting over the jinja2-docsite etc to the ansible/docsite repo - Move the jinja-docsite source files to the main branch docsite#182
• WIP PR so you can see what we’re doing: Create AWX docsite with RST content  awx#14328
• controller docs are being ported to ansible/awx to become AWX docs! Create AWX docsite with RST content  awx#14328

Action Items

• samccann to announce awx-operator docs and kudos to bullhorn when it's published
• add to ecosystem page as well (awx-operator)

Full logs avalable at https://ansible-accounts.ems.host/_matrix/media/v1/download/ansible.im/10d744192fd8b830d50795ae7890807ff5ce496f

[samccann]

Meeting Summary at 2023-08-22 15:02:28

Info Items

Time	User	Message
2023-08-22 15:02:28	samccann	^info as a reminder, we are using the Ansible matrix meeting bot. The commands are ^info and ^action and anyone (on matrix) can use those commands to add to the meeting summary
2023-08-22 15:06:24	samccann	^info awx operator docs have been published! https://awx-operator.readthedocs.io/en/latest/
2023-08-22 15:09:27	samccann	^info the Ansible forum will be open soon. DaWGs meeting agenda and meeting summaries will be posted there in the future.
2023-08-22 15:09:56	samccann	^info so we'll stop using #678 at that point and just leave a breadcrumb to the agenda in the forum
2023-08-22 15:25:19	samccann	^info we will add a @docs group to the forum. Let us know if you want to join it.
2023-08-22 15:34:02	samccann	^info debating if we should open up the DaWGs meeting to ecosystem projects, with the understanding we can advise and share info, but may not be able to fix docs issues etc
2023-08-22 15:34:55	samccann	^info we can help create guidelines/style guides/templates/manage the rtd setup, but our main goal should stay as core/package docs
2023-08-22 15:35:52	samccann	^info docsite PR to port over the templates and build stuff ansible/docsite#182
2023-08-22 15:39:59	samccann	^info automation is now creating dependency PR updates for us - ansible/ansible-documentation#316
2023-08-22 15:40:46	gotmax23	^info ansible/ansible-documentation#317 discusses the backport strategy for requirements updates
2023-08-22 15:42:41	samccann	^info once we apply the requirements updates to stable branches, this automatioin will limit updates to minor version changes on those stable branches
2023-08-22 15:45:31	gotmax23	^info Tracking the requirements update process is tracked in ansible/ansible-documentation#312

Action Items

Time	User	Message
2023-08-22 15:24:41	samccann	^action samccann to create a docs group w/ tvo and acozine and herself

Full log available here:[full_log.txt|attachment](upload://hZLWCgcEvKjbBZSZJF50hY1BNLw.txt)

[samccann]

Ansible Docs | #docs:ansible.com | 2023-08-29 15:01:04

Info Items

Time	User	Message
2023-08-29 15:01:04	Oranod	^info as a reminder, we are using the Ansible matrix meeting bot. The commands are ^info and ^action and anyone (on matrix) can use those commands to add to the meeting summary
2023-08-29 15:01:56	Oranod	^info here’s the agenda: DaWGs (Documentation Working Group) Meeting Agenda 2023 · Issue #678 · ansible/community · GitHub
2023-08-29 15:06:49	Oranod	^info awx operator docs are out and added to the ansible namespace on RTD. Ansible AWX Operator Documentation
2023-08-29 15:08:06	Oranod	^info there’s also a PR to update the link on the ecosystem page if anyone wants to review/approve: update awx operator docs home by oraNod · Pull Request #183 · ansible/docsite · GitHub
2023-08-29 15:14:42	Oranod	^info using RTD for ansible-core and the ecosystem docs. I sent a PR to add a RTD config for ansible-core docs and plan to revisit it this week. [WIP] Host core docs on readthedocs by oraNod · Pull Request #296 · ansible/ansible-documentation · GitHub
2023-08-29 15:32:39	Oranod	^info also it’s probably not a good idea to try and shoehorn the proposed ecosystem docs into the ansible-documentation repository. that would complicate the RTD set up and, really, perhaps it’s not something that people who contribute to the package or core docs actually care about.
2023-08-29 15:34:26	Oranod	^info samccann merged my docsite PR and now the GitHub - ansible/docsite: Static HTML and assets for docs.ansible.com repo is all new and shiny. thanks again to Sviat for the stellar review on the build side.
2023-08-29 15:43:26	Oranod	^info we’re working through porting over content from the private product-docs repo to ansible/awx. here’s the PR: Create AWX docsite with RST content by oraNod · Pull Request #14328 · ansible/awx · GitHub
2023-08-29 15:46:58	Oranod	^info open floor

Action Items
Time User Message
2023-08-29 15:28:10 Oranod ^action @Oranod to spend time preparing the HackMD to describe the build and deploy changes for ansible-core and package docs for community review

Full meeting log:https://forum.ansible.com/t/meeting-log-ansible-docs-2023-08-29-1504/196#ansible-docs-docsansiblecom-2023-08-29-150104-1

[oraNod]

Agenda - 2023-Sept 05

Welcome!!

This meeting is open to everyone. We discuss topics related to Ansible project documentation and the tooling that publishes that documentation to docs.ansible.com. While the meeting at times goes deeply into some topics, we welcome newcomers and new contributors and are always willing to explain what we are discussing to help you follow along on the topics.

For those taking meeting minutes:

We now use the Matrix meeting bot. Start the meeting with

1. !startmeeting Documentation Working Group aka DaWGs
2. @room Meeting time! Who is here to talk the docs?

Then as you progress, use ^topic to start each main topic below
Then use ^info to summarize what is discussed, and ^action for any action items proposed.

When the meeting is done:

1. Copy this comment into a new comment with the upcoming meeting date changed to the following Tuesday date.
2. If the meeting bot is not yet adding the meeting summary to the forum
   a. Copy the info and action summaries from matrix into this comment to overwrite the old agenda with the meeting minutes.
   b. Add a link to download the full meeting log.

We currently focus on the Ansible package and ansible-core releases, tracking the docs issues and PRs.

Documentation work

---

• review any docs-based action items from last week

New work:

• Who wants to be in the @docs group in the forum?

ongoing work:

• awx operator docsite is live! https://awx-operator.readthedocs.io/en/latest/
• cheatsheet updates
• using RTD for ansible-core
• Controller > AWX docs effort: Create AWX docsite with RST content  awx#14328
• New [documentation issues and requests for help](https://github.com/ansible/ansible-documentation/issues and the good first issues
  • moving more collection scenario guides. see community.general for it in action!
• Pending docs PRs that need help

Docs tooling (antsibull etc)

• Action Item review

Open Floor

[samccann]

NOTE - The Agenda is now tracked at https://forum.ansible.com/t/documentation-working-group-agenda/153/7
Meeting minutes are now at https://forum.ansible.com/tags/c/workflow/meetbot/16/documentation