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 https://github.com/ansible-community/antsibull-docs/pull/90

Documentation updates

• looking for feedback on how to open up the docs publishing pipeline - https://github.com/ansible-community/community-topics/issues/174

Actions

• [x] @samccann to change ...something... so autobot messages on docs issues point to new agenda.
• [x] 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
• [x] @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
• https://github.com/ansible/ansible/pull/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: https://github.com/ansible-community/community-topics/issues/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

• [x] @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 https://github.com/ansible-community/community-examples/issues/2#issuecomment-1378323986

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 https://github.com/ansible-community/community-topics/issues/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

• [x] samccann to simplify community personas and create community-topic to discuss (post in bullhorn etc)
• [x] 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 https://github.com/ansible-community/community-topics/issues/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 - https://github.com/ansible/ansible/pull/79370

• When that's done we can bump antsibull-docs to support it - https://github.com/ansible/ansible/pull/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

• [x] samccann to summarize feedback here and pass it on to devtools team. Also ask what their goals are for this site
• [x] 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
• [x] samccann to see status of marking some plugins as private - https://github.com/ansible/ansible/pull/79370 (waiting on core approval)

[samccann]

2023-01-31

Action Item updates

• closed samccann to summarize feedback here and pass it on to devtools team.
• open -Looking for community maintainer(s) for the sphinx ansible theme
• closed samccann reinvite zodbot when it goes on holiday
• solution to zodbot was to open an issue like this one -https://pagure.io/fedora-infrastructure/issue/11103
• closed samccann to see status of marking some plugins as private - https://github.com/ansible/ansible/pull/79370
• open oranod to update docs requirements versions before Feb 20

Documentation updates

• Ansible 8 roadmap up for vote - https://github.com/ansible-community/community-topics/issues/176
• booleans and ansible-lint -need help asking collection owners to implement these. See https://github.com/ansible-community/community-team/issues/60 for list that still needs issues opened on the collection itself.
• Archived 2.6 docs and will put redirects in place next week from the old docs to /latest/ - https://docs.ansible.com/archive/ansible/2.6/
• will likely archive the examples repo as it never got any traction - https://github.com/ansible-community/community-examples/

personas and revamping the docsite

• feedbck wanted - see the docsite personas at https://hackmd.io/pZb5w5JFRQW3RJ73n23tlw
• full discussion at https://github.com/ansible-community/community-topics/issues/175
• the jinja docsite is available for review / contribution at https://github.com/ansible/jinja-docsite

Logs

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

[samccann]

2023-02-14

Action Item updates:

• open -Looking for community maintainer(s) for the sphinx ansible theme
• https://pypi.org/project/sphinx-ansible-theme/
• https://github.com/ansible-community/sphinx_ansible_theme
• open samccann to update docs requirements versions before Feb 20
• https://github.com/ansible/ansible/pull/79930

Documentation updates

• Ansible 8 roadmap ready to merge
• looking for help on documenting how to run tests with Ansible pre-releases - https://github.com/ansible-community/community-topics/issues/156
• booleans and ansible-lint -need help asking collection owners to implement these. See https://github.com/ansible-community/community-team/issues/60 for list that still needs issues opened on the collection itself.
• Archived 2.6 docs and will put redirects in place next week from the old docs to /latest/ - https://docs.ansible.com/archive/ansible/2.6/
• examples repo archived as it never got any traction - https://github.com/ansible-community/community-examples/

personas and revamping the docsite

• goal is to evaluate who the people are in our larger Ansible community, and how best to serve them with targeted docs and journeys through our projects etc
• https://hackmd.io/pZb5w5JFRQW3RJ73n23tlw?both#/
• https://github.com/ansible/jinja-docsite
• the jinja-docsite repo is a first stab at improving the layout and design of docs.ansible.com based on personas and is open for contributions
• overarching goal is to ensure the new docsite belongs to the community and provides community with the tools necessary to design/improve/add to it
• see https://ansible.github.io/jinja-docsite/ to view how the main branch looks for the proposed new docsite

Actions

• [ ] @all - review the requirements updates in https://github.com/ansible/ansible/pull/79930
• [ ] @samccann to create a list of 'docs stuff that needs updating for a new release' to catch things like roadmap updates early on
• [ ] @Clone the jinja-docsite repo and show us how you'd like to improve docs.ansible.com https://github.com/ansible/jinja-docsite

Logs

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

[samccann]

2023-02-21

Action Item updates

• open -Looking for community maintainer(s) for the sphinx ansible theme
• https://github.com/ansible-community/sphinx_ansible_theme/issues/84 this one
• one of the drawbacks of current theme is that black header bar at the top. We are open to redesigning the theme to remove/replace and keep it all community-focused
• https://github.com/ansible-community/sphinx_ansible_theme/issues/41
• open samccann to create a list of 'docs stuff that needs updating for new release' to catch things like roadmap updates early on.
• open - all - clone the jinja2-docsite repo and show us how you'd like to improve docs.ansible.com https://github.com/ansible/jinja-docsite
• closed samccann to update docs requirements versions before Feb 20
• https://docs.ansible.com/ansible/devel/roadmap/ROADMAP_2_15.html#release-phase

opening up community docs build

• as part of the initiative to open up the build for package docs I've looked at a number of options. one of the things that it's stuck on is the fact that you need a rather large host to handle the sphinx-build for the package docs. one of the options is doing a lift and shift of the content in docs/docsite from the ansible/ansible repository to another repo.
• some of the drivers for this change include getting rid of the internal jenkins jobs the publish the docs... but primary driver is to make sure the package docs build is something the community can take ownership of and directly work on

Actions

• [x] @Don Naro to follow up with current maintainer of ansible-sphinx-theme on proposal to replace it with something else

Logs

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

[samccann]

2022-02-28

Action Item updates

• aranod spoke to owner of ansible sphinx theme and he is +1 for creating an updated theme.
• Add your thoughts/requirements for a new theme to https://github.com/ansible-community/sphinx_ansible_theme/issues/41

Documentation updates

• we're gathering docs feedback for execution environments at https://github.com/ansible-community/community-team/issues/161

• we'll fire off the script soon to open issues against collections to support true/false booleans - https://github.com/ansible-community/community-team/issues/60

• personas and user journeys moving along https://github.com/ansible-community/community-topics/issues/175

• View the personas at https://github.com/ansible/docsite/blob/personas/personas/ansible-docsite-personas.md

• view the user journeys at https://github.com/ansible/docsite/blob/personas/user-journeys/ansible-user-journey-maps.md

• community members will go ahead with semantic markup for docs - https://github.com/ansible-community/community-topics/issues/53#issuecomment-1441965593

• community members evaluating supporting private plugins for collections in projects under their control - https://github.com/ansible-community/community-topics/issues/154#issuecomment-1441951838

zodbot not present so see matrix directly for logs.

[samccann]

2023-03-07

docs landing pages

• the community team has put together a first set of user journeys based on the personas, which are available at https://github.com/ansible/docsite/blob/personas/user-journeys/ansible-user-journey-maps.md
• we'd love to get review and feedback / whatever input folks in the community have got
• we're using these journeys to build a new docsite that will replace docs.ansible.com in a few weeks. you can find the work in progress site (and send a PR to help) here: https://github.com/ansible/jinja-docsite
• you can see the WIP docsite at -https://ansible.github.io/jinja-docsite/
• docsite should help experienced users find things quickly like precidence list, jinja2 help etc
• folks can add feedback to https://github.com/ansible-community/community-topics/issues/175
• we need some help fleshing out the WIP pages - feel free to grab one of the issues here and start hacking: https://github.com/ansible/jinja-docsite/issues
• these are based on the journeys defined in https://github.com/ansible/docsite/blob/personas/user-journeys/ansible-user-journey-maps.md
• https://www.lilatomic.ca/posts/ansible_httpapi_plugins/ <= has some VERY good plugin dev articles

linking to external useful content for learners

• where could we use/highlight good external content like https://www.lilatomic.ca/posts/ansible_httpapi_plugins/

Open Floor

• everyone who hasn't yet, please don't forget to participate in the vote for semantic markup (https://github.com/ansible-community/community-topics/discussions/205) and/or the vote for what kind of mechanism to use for private plugins in collections (https://github.com/ansible-community/community-topics/discussions/204)
• voting started for the community planning strategy - https://github.com/ansible-community/community-topics/issues/201#issuecomment-1458480432

Actions

• [ ] @all - open issues on https://github.com/ansible/jinja-docsite/issues for your feedback on the current design at https://ansible.github.io/jinja-docsite/
• [x] @samccann to review top page hits and add to https://github.com/ansible/docsite/issues/161 as potential quicklinks

Logs

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

[felixfontein]

Two active community votes on documentation issues:

• Semantic markup: https://github.com/ansible-community/community-topics/discussions/205
• Private plugins/modules - how to mark them: https://github.com/ansible-community/community-topics/discussions/204

[samccann]

2023-03-14

Action Item updates:

• open samccann to create a list of 'docs stuff that needs updating for new release' to catch things like roadmap updates early on.
• closed samccann to review top page hits and add to https://github.com/ansible/docsite/issues/161

personas and revamping the docsite

• see https://ansible.github.io/jinja-docsite/ for current prototype pages. This will be the new pages soon on docs.ansible.com so feedback needed on this!
• log issues or maybe fix a few at https://github.com/ansible/jinja-docsite/blob/devel/CONTRIBUTING.md
• https://ansible.github.io/jinja-docsite/user.html
• docsite feedback - main page is still very Ansible-core focused and links to 'other resources' is less obvious that it brings you to a new page with more details on the journey so to speak
• the term Ansible is overloaded. Does it really reflect things like navigator, awx etc etc?
• https://github.com/ansible/jinja-docsite/issues/31
• new docsite needs at least the following before it goes live
• 1 - have a new 'place' for all the existing pages. Some of those new places might be the ecosystem page, other's have real pages so to speak
• 2 - fix basic responsive design issues
• 3 - translation and prior version stuff has to work (core and controller)
• 4. Needs more early-user/tester feedback. maybe a focus group to use it for a time?
• could ask user channel for help, or a live zoom or something...
• would also be good if those 'other resources' links were more obvious. We knew there were subpages but not how to get to them until we fiddled a bit
• we may not need a full minimal landing page but something on the main page for 'what do we mean when we say Ansible'. Also remember people have the url docs.ansible.com memorized so many people will bypass any higher-level website page and come straight here.

Open Floor

• semantic markup is (mostly) here!
• add your thoughts to the static site generator for potential new website - https://github.com/ansible-community/community-topics/issues/210

Logs

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

[samccann]

Was discussed in https://github.com/ansible/community/issues/678#issuecomment-1448521392 log, there already is a repo for highlighting external-to-docs Ansible resources for learning etc: https://github.com/ansible-community/awesome-ansible

[samccann]

2023-03-28

Semantic markup enhancments

• semantic markup is ready to go and antsibull-docs update pr already merged
• :+1: - we will not post docs about how to use semantic markup in 2.15 but docs will appear on devel. This gives time for other projects to catch up

jinja docsite

• we have an mvp (minimum viable project) of the new docsite for Ansible community
• https://ansible.github.io/jinja-docsite/
• https://github.com/ansible/jinja-docsite/labels/Review
• Need to identify the next steps to move forward with this and take over docs.ansible.com
• :+1: - we will broadcast a call for testing the prototype docsite this week and flip to these pages on docs.ansible.com on Tuesday after DaWGs final decision

Documentation updates

• Do we as community support additional install instructions - https://github.com/ansible/ansible/pull/80308 ?
• note we removed this page a year ago because core team only verifies pip installs. Someone else added a few more on this page, and now it seems to be growing to be what it was before... we removed it.
• we want the install instructions to be maintained so will ask the community WG for advice

Actions

• [x] @samccann oranod create issues to track moving jinja2 docsite to ansible/docsite and any jenkins changes
• [x] @samccann open a community topic to decide which packages go on the non-pip install docs page
• [x] @samccann to post community-topic on what stays or goes on tools docs page

Logs

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

[felixfontein]

• [x] Should https://github.com/ansible/ansible/pull/80240 be merged for 2.15 or for 2.16?

[samccann]

Meeting Minutes 2023-04-04

Action Item updates

• closed - create issue to move protype docsite to ansible/docsite repo - https://github.com/ansible/docsite/issues/147
• closed - create issue to ask what tools we should include on the tools page - https://github.com/ansible-community/community-topics/issues/220
• Please add your thoughts to that issue so we can have some guidelines for that docs page
• closed decide what guidelines for adding distro installs
• guideline is that the distro has to be 'well maintained and updated' and add a link to the distro 'owners' or github for users to open any issues if there are problems with the install instructions

Docsite update

• latest version of the docsite prototype is at https://ansible.github.io/jinja-docsite/
• remaining PRs: https://github.com/ansible/jinja-docsite/pulls
• we will go live with these pages after merging the final PRs in the queue (aka next day or so)
• further feedback on the docsite should go as issues at https://github.com/ansible/docsite/issues
• "go live" plan for the user journey-based docsite. merge remaining PRs on the jinja-docsite repo > generate a build > push the generated HTML to ansible/docsite > hit jenkins
• that plan outlines the sequence of events. beyond that I think we should probably rebuild the site with nikola and clean things up. then move everything to ansible/docsite if the initial feedback is OK and nobody screams at us to revert everything.
• ansible/docsite repo will be the raw HTML of the jinja2 site for a time, while we have the feedback period. Any changes will still have to be in the jinja2 site and regenerate the HTML from there
• we will attempt to use analytics to track how many people use the old site pages to determine when the feedback period ends and we replace ansible/docsite entirely with the jinja2 site (or nikola stuff)

Open Floor

• 2.6 redirects are in place, 2.7 archive coming next. 2.8 builds are busted so...may never get archived

[samccann]

2023-04-11

Documentation Updates

• awx operator looking for docs help to create a docsite and split up the big readme into .md files for said docsite - https://github.com/ansible/awx-operator
• we will coordinate the project in github for async planning etc and use Thursdays on #docs matrix/irc channel for when we need to chat live for questions etc
• new docsite is going well... very few people switching to the old site
• docs archiving nearly complete! Will redirect 2.7 soon and may stop there
• working on a shared documentation style guide (rst and md) that can be used across all ansible projects
• Always welcoming help on open issues https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs or easyfix issues https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs+label%3Aeasyfix
• https://docs.ansible.com/core.html
• https://docs.ansible.com/archive/ansible/2.3/

Actions

• [x] @samccann to create tracking issues on awx operator docs effort
• [ ] @oraNod to review open issues on docsite and mark some easyfix or worth highlighting in this channel

Logs

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

[samccann]

2023-04-18

Action Items

• open @oraNod to review open issues on docsite and mark some easyfix or worth highlighting in this channel
• closed @samccann to create tracking issues on awx operator docs effort https://github.com/ansible/awx-operator/issues/1356

Documentation Updates

• have multiple requests coming in for help with docs across various ansible projects and collection(s)
• these are smaller projects so good candidates for people who want to get a start-to-end project under their belts in docs land
• Need help on collection dependencies docs issue - https://github.com/ansible/ansible-documentation/issues/77
• looking for help on creating a cheatsheet for ansible commands - https://github.com/ansible/ansible-documentation/issues/48
• Ansible 8 alpha docs up on test at http://docs.testing.ansible.com/ansible/8/index.html Please review and let us know if you see problems.

doc tools

• we've added some "quicklinks" to the new docsite layout. you can find them on the index, user, developer, and maintainer pages. currently on the preview site at: https://ansible.github.io/jinja-docsite/

Actions

• [x] @samccann to create community-topic to discuss https://github.com/ansible/ansible-documentation/issues/77

Logs

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

[samccann]

2023-04-25

Action Items

• open @oraNod to review open issues on docsite and mark some easyfix or worth highlighting in this channel

Documentation updates

• https://github.com/ansible-middleware
• looking for docs help for wildfly collection - https://github.com/ansible-middleware/wildfly/issues/105
• initial request for help is to review/edit existing readme files to clarify etc. Then can consider adding content from the blog posts into the readme where appropriate
• Ansible 8 alpha docs up on test at http://docs.testing.ansible.com/ansible/8/index.html Please review and let us know if you see problems.
• looking for help on creating a cheatsheet for ansible commands - https://github.com/ansible/ansible-documentation/issues/48
• https://docs.ansible.com/ansible/latest/command_guide/command_line_tools.html

Open Floor

• we've migrated Ansible Sign docs over to readthedocs and trying to get Galaxy to RTD as well in the next couple of weeks. that will mean all active projects in the ecosystem will be hosted on RTD (another step towards consistent ecosystem)
• the ecosystem page is updated to include edge and is now in alphabetical order too, which hopefully helps with navigation https://docs.ansible.com/ecosystem.html
• the docsite journeys have been updated to reflect some of the changes we made while building out the docs.ansible.com pages. https://github.com/ansible/docsite/blob/main/data/journeys/docsite-journeys.md

Logs

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

[samccann]

Agenda - 2023-May-2

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.

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
• [ ] starting mini-team to help awx operator project set up a docsite.

ongoing work:

• [ ] Community EEs - what's missing for these in docsland etc?
• [ ] docsite status
• [ ] 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 tooling (antsibull etc)

• [ ] Action Item review

Open Floor

[oraNod]

2023-05-09

general updates

• carrying on from some of the efforts to provide contributor opportunities for doc writers, there has been some work going on to create a writer's toolkit that will provide resources for people who want to do some writing work
• antsibull-docs 2.0.0a1 is released so update to the new version and try it out 🚀
• speaking of releases, core-2.15 is coming up next week on the 15th. I'll be helping finish up the release checklist and thought I'd drop the info in if someone else wants to get involved in the proceedings
• https://github.com/ansible/ansible-documentation/issues/76
• we'll basically need to update the version switcher by merging and backporting samccann 's PR
• https://github.com/ansible/ansible/pull/80556
• then we need to set the version to 2.15 on the stable-2.15 branch

Open Floor

• https://github.com/ansible-community/community-topics/issues/202
• I recently got the chance to share some playbooks I wrote for converting markdown or rst to asciidoc but you could adapt them for other conversions. maybe someone out there might find them useful for their doc set.
• https://github.com/oraNod/ansible-conversion-playbooks

Logs

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

[oraNod]

2023-05-16

Meeting summary

• meeting agenda at https://github.com/ansible/community/issues/678#issuecomment-1549686517 (oranod, 15:01:07)
• we all miss samccann and look forward to her return (oranod, 15:07:56)
• quick update on core 2.15 doc publishing. I've been waiting on a backport to stable-2.15 but that should be merged shortly and I'll get the docs published and updated (oranod, 15:10:16)
• docsite update PR at: https://github.com/ansible/docsite/pull/171 - this adds the ansible_community.html page that we've talked about in previous meetings to fix a "gap" in one of the pages that is deprecated with the new docsite. but analytics seem to indicate there are people still hitting that page from bookmarks. (oranod, 15:13:03)
• that docsite PR also updates the "oldsite" controller pages for 4.2.2 TVo (oranod, 15:13:34)
• last week we also talked about the old tower page at: https://docs.ansible.com/ansible-tower/index.html - I've looked into that but still need to figure out if it is automatically updated/generated from a repo somewhere or not. (oranod, 15:15:40)
• community execution environments. what is missing? this was a topic that was brought up at some previous meetings. there has been an update since that I thought would be relevant. (oranod, 15:29:24)
• andersson007_ from the community team is working on https://github.com/ansible-community/community-team/issues/230 to make some improvements to the state of things with community ee's (oranod, 15:30:04)
• LINK: here is the ticket for doc issues to add command cheatsheets: https://github.com/ansible/ansible-documentation/issues/48 (oranod, 15:37:09)
• LINK: community writers project board https://github.com/orgs/ansible-community/projects/3 (oranod, 15:39:50)
• LINK: https://github.com/orgs/ansible-community/projects/3/views/1 (Dule_Martins0383, 15:40:36)
• the Steampunk project has added complete documentation for all versions of all Ansible Collections that exist on Ansible Galaxy! You can find it here: https://docs.steampunk.si/plugins/ (oranod, 15:42:14)
• open floor (oranod, 15:45:02)

Logs

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

[oraNod]

2023-05-23

• updates to the docsite repo have been taking place to simplify some of the html pages https://github.com/ansible/jinja-docsite (oranod, 15:05:40)
• LINK: https://github.com/orgs/ansible-community/projects/3/views/1?layout=board (oranod, 15:33:05)

• Open Floor (oranod, 15:37:35) Logs

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

[samccann]

2023-05-30

Documentation Updates

• Ansible 8 will be released today! Docs release prep in the works as well.
• ansible-core 2.12 is EOL... will update the docs accordingly this week

Execution Environments

• ansible-builder 3.0 is out and needs new/updated docs
• andersson007_ is leading the effort and drafting out some of this
• see https://github.com/ansible-community/community-team/issues/230 to help out
• there is also this PR where folks can help with documenting the ENV ANSIBLE_GALAXYSERVER* vars: https://github.com/ansible/ansible-builder/pull/538
• these EE docs are a new 'category' in that the how to guide will span more than one Ansible community project (builder, AWX, stand-alone use, etc)
• AWX might have similar content to controller on using EEs in job templates - https://docs.ansible.com/automation-controller/latest/html/userguide/execution_environments.html
• controller has https://docs.ansible.com/automation-controller/latest/html/userguide/execution_environments.html and AWX has https://github.com/ansible/awx/blob/devel/docs/execution_environments.md for EEs in job templates (tho the latter may not be up-to-date)
• and in general, most docs are not up todate with Builder 3.0
• Need help on collection dependencies docs issue - https://github.com/ansible/ansible-documentation/issues/77 and https://github.com/ansible-community/community-topics/issues/224

Ansible command cheatsheet

• looking for help on creating a cheatsheet for ansible commands - https://github.com/ansible/ansible-documentation/issues/48

Ansible 8 release

• Ansible 8 docs up on test at http://docs.testing.ansible.com/ansible/8/index.html Please review and let us know if you see problems. Ignore version switcher as those PRs still need to be backported etc
• major kudos to oranod for getting ansible-core 2.15 docs published and the prep work for Ansible 8

Doc tools and docsite

• here is the link with details if anyone wants to contribute to improving the jinja templates for the docsite: https://github.com/ansible/jinja-docsite/issues/108

Adding to the community-writers project board

• this board is for community members interested in growing their writing skills or technical writers interested in helping with ansible docs
• two main categories of issues - those that can be fixed with Edit on Github, or those that require git knowledge
• you can also post a PR for techwriter review there
• copy a link from your issue or PR and add it to the board
• a writer assigns the issue to themselves in the dropdown box on that page so other's know someone has taken it

Actions

• [x] @samccann to inform community-writers about EE epic for a place to help out
• [x] @samccan to ask on reddit 'how do you use this cli command' type questions for feedback

Logs

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

[samccann]

2023-06-06

Action Items

• closed samccann to inform community-writers about EE epic for a place to help out editorially and with info architecture etc
• closed issue in community-topic for requesting cheatsheet help and on reddit as well - https://github.com/ansible-community/community-topics/issues/232

Documentation Updates

• so far minor feedback on cheatsheet ideas but just put the community-topic on this week's agenda so might get more attention after tomorrow's meeting
• a lot of attention happening on builder docs - https://github.com/ansible/ansible-builder/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
• awx operator mkdocs PR - https://github.com/ansible/awx-operator/pull/1363
• I opened this issue to improve / rewrite getting started if anyone is interested: https://github.com/ansible/ansible/issues/80941

Moving (some) community docs out of ansible/ansible

• moving community docs out of ansible/ansible- https://github.com/ansible-community/community-topics/issues/240
• moving source files makes sense to make updates easier by community. Ideally they publish to the same urls they live at today to keep SEO in place and reader familiarity

Logs

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

[samccann]

2023-06-13

Action Items

• closed samccann to inform community-writers about EE epic for a place to help out editorially and with info architecture etc
• closed issue in community-topic for requesting cheatsheet help and on reddit as well - https://github.com/ansible-community/community-topics/issues/232

Moving docs out of ansible/ansible

• this is part of putting package docs under ansible steering committee/community control. See https://github.com/ansible-community/community-topics/issues/243
• an interim step is to move all docs out to ansible/ansible-documentation. From there, we can iterate faster to get to the point where the community package docs are under community control (likely another repo in ansible-community org) and separate from core docs.
• starting this Thursday, we'll test out the new ansible/ansible-documentation repo and publish devel docs from there.
• this also means docs PRs in ansible/ansible in the next two weeks will be asked to move over to ansible/ansible-documentation

Documentation updates

• removing local copies of interphinx links - https://github.com/ansible/ansible/pull/80994
• https://github.com/ansible/ansible/pull/80994#issuecomment-1589265337
• considering how to handle how-to guides that include more than one project. See the EE issues for an example - https://github.com/ansible-community/community-team/issues/243#issuecomment-1588912447
• should a quickstart tutorial include more than one project? General agreement is EEs do need to talk about more than one project. Just building an EE is useless w/o showing how to use the end result for example
• https://github.com/ansible/community-docs/pull/60 is the content we're talking about

Open Floort

• looking for feedback on how to handle enviroment variables - https://github.com/ansible-community/antsibull-docs/issues/164

Logs

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

[samccann]

2023-06-20

Moving docs out of ansible/ansible

• this is part of putting package docs under ansible steering committee/community control. See https://github.com/ansible-community/community-topics/issues/243
• an interim step is to move all docs out to ansible/ansible-documentation. From there, we can iterate faster to get to the point where the community package docs are under community control (likely another repo in ansible-community org) and separate from core docs.
• new docs repo is https://github.com/ansible/ansible-documentation
• Folks are expressing concerns that we will lose technical contributors to docs in the new repo over time, and the long-term health of the documentation will be impacted by this move
• identified risk - the docs lose technical accuracy over time because it's an extra step to remember to open a docs PR in another repo. Identified benefits - aster iteration on antsibull-docs updates, ability to split the core from community docs, and lead toward full community control over the documentation

Getting Started guide revamp

• https://github.com/ansible/ansible-documentation/pull/14
• https://github.com/ansible-community/community-team/issues/243#issuecomment-1588912447
• EE content that is being discussed is here - https://github.com/ansible/community-docs/tree/main/execution_environments
• https://docs.ansible.com/ansible/latest/getting_started/index.html
• https://github.com/ansible/community-docs/tree/main/execution_environments
• :+1: The EE content (overview and getting started) should be its own guide in the Getting started navigation area on docs.asible.com

Logs

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

[samccann]

Meeting minutes - 2023-June 27

Moving docs out of ansible/ansible

• this is part of putting package docs under ansible steering committee/community control. See https://github.com/ansible-community/community-topics/issues/243
• an interim step is to move all docs out to ansible/ansible-documentation. From there, we can iterate faster to get to the point where the community package docs are under community control (likely another repo in ansible-community org) and separate from core docs.
• first week status - so far so good. Multiple publishing events on multiple branches and all looks good
• next steps - We evaluate on Thursday to see where we stand on this effort. Assuming all goes well and we feel confident on core maintaining technical stewardship of the content, we will fix any remaining items
• short list of todo items identified so far - https://hackmd.io/c9SEj2FaRvKF5UhXNl9NtA#To-do-before-split
• we've also discussed some messaging and strategy to avoid the loss of any contributors from the overhead of a separate repo, as came up last week

Documentation updates

• Progressing on scaffolding to create docs for awx operator -https://github.com/ansible/awx-operator/pull/1363
• Need to cherrypick some commits to fix CI errors
• Next step - separate out readme into individual files in the /docs folder and add to mkdocs. Then create readthedocs structure and publish!
• Japanese translation published for 2.15 https://docs.ansible.com/ansible-core/2.15_ja/index.html
• WG agreed to drop the oldsite toggle from dropping the oldsite toggle from docs.ansible.com. Less than 0.6% of visitors going to that oldsite at this point.

Getting Started updates

• last week we talked a little about revamping the Getting started with Ansible content and there are some updates in that area.
• moved the introduction into the getting started based on user feedback - https://docs.ansible.com/ansible/devel/getting_started/introduction.html
• Two PRs up for review as well -
• PR to refocus getting started on using single directory projects instead of files scattered around is here: https://github.com/ansible/ansible-documentation/pull/29
• This PR adds an EE getting started section: https://github.com/ansible/ansible-documentation/pull/18(edited)

[samccann]

Meeting minutes - 2023-July 4

documentation work

• https://github.com/ansible-community/community-topics/issues/243
• we've agreed on July 10th as the date for the split from ansible/ansible to ansible/ansible-documentation
• after the split occurs all docs and example directories will no longer be present in ansible/ansible (this PR: https://github.com/ansible/ansible/pull/81011)
• currently working my way through the to do checklist here: https://hackmd.io/@ansible-community/rkzSKCEvh#To-do-before-split
• https://github.com/ansible/ansible-documentation/issues/36
• samccann and I have spoken to the core team. I put down some details about how we can reduce contributor overhead. samccann and some of the core folks agreed on an approach to track doc items using a project board
• samccann can get into the nitty gritty details next week but I think it's safe to say we've been discussing the concerns and - fingers crossed - we should be alright. personally I have zero concerns with losing any sort of technical stewardship from core.

docsite updates

• I opened a PR to remove the oldsite toggle from the landing pages on docs.ansible.com
• https://github.com/ansible/jinja-docsite/pull/122

Getting Started updates

• last week we got a PR merged to simplify getting started to focus a bit more on projects with a single dir structure
• https://github.com/ansible/ansible-documentation/pull/29
• https://docs.ansible.com/ansible/devel/getting_started/index.html
• you can see the changes on devel now
• there is also an ongoing discussion around adding EE docs to getting started
• https://github.com/ansible/ansible-documentation/pull/18
• I've been thinking about it some more and am going to propose that we create an ansible/ecosystem-documentation project where we can document tutorials and how tos for Ansible projects
• pretty much just the details here: https://github.com/ansible/ansible-documentation/pull/18#discussion_r1250599233
• I hope this would help us avoid repeating a similar mistake with ramming too much content into a single doc set

Logs

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

[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
• https://github.com/ansible/ansible-documentation/issues/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...
• https://github.com/ansible/ansible-documentation/pull/18#issuecomment-1628779074
• :+1: 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

• https://github.com/ansible/jinja-docsite/pull/122
• I've sent a PR to remove the oldsite toggle as agreed at the meeting before last
• https://github.com/ansible/jinja-docsite/pull/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 - https://github.com/ansible-community/community-team/issues/310

Open Floor

• https://github.com/ansible/ansible-documentation/issues/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
• https://github.com/ansible/ansible-documentation/pull/118
• https://github.com/ansible/ansible-documentation/issues/69
• https://github.com/ansible-community/community-topics/issues/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 - https://github.com/ansible/ansible-documentation/issues/152.

Labelling strategy

• setting up labels in the docs repo - https://github.com/ansible/ansible-documentation/issues/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 - https://github.com/ansible/ansible-documentation/issues/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 - https://github.com/ansible/ansible-documentation/pull/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

• https://github.com/ansible/ansible-documentation/issues/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 - https://github.com/ansible/ansible-documentation/issues/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? https://github.com/ansible/ansible-documentation/issues/101#issuecomment-1646103865
• 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

• https://github.com/ansible/ansible-documentation/issues/66

Preferred terminology

• adding project terms to style guide - https://github.com/ansible/ansible-documentation/issues/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 https://github.com/ansible-community/community-team/issues/310
• porting over the jinja2-docsite etc to the ansible/docsite repo - https://github.com/ansible/docsite/pull/182
• WIP PR so you can see what we’re doing: https://github.com/ansible/awx/pull/14328
• controller docs are being ported to ansible/awx to become AWX docs! https://github.com/ansible/awx/pull/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 https://github.com/ansible/community/issues/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 https://github.com/ansible/docsite/pull/182
2023-08-22 15:39:59	samccann	^info automation is now creating dependency PR updates for us - https://github.com/ansible/ansible-documentation/pull/316
2023-08-22 15:40:46	gotmax23	^info https://github.com/ansible/ansible-documentation/issues/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 https://github.com/ansible/ansible-documentation/issues/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](https://forum.ansible.com/u/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: https://github.com/ansible/awx/pull/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