DaWGs (Documentation Working Group) Meeting Agenda 2020

[samccann]

This tracks the DaWGs (Documentation Working Group )meetings for Ansible docs from Feb. 2020 through Dec. 2020. For 2021 agendas, see #579.

This team uses the following GitHub tracking boards:

• ansible Base (covering all the user/developer guides etc)
• Ansible-maintained collections - what needs to happen in docs for these collections.
• docs pipeline - the work and dependencies to getting module docs from collections back onto docs.ansible.com/ansible.

Please leave a comment regarding any agenda item you wish to discuss. If you don't show up for the meeting, your item will be skipped.

If your IRC 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 #ansible-docs on freenode IRC!

See #389 for prior meeting minutes.

[samccann]

2020-04-14

release notes and changelogs for ACD

• [?w] changelog process for collections ansible-collections/overview#18 (comment)
• survey so far leads to Move ansibullbot into ansible/ansibullbot #2 option, with a fallback to manual links added to the ACD changelog for those collections who don't have the changelog in a fixed location we could link to programmatically
• Still hoping to gather some more feedback from collection owners
• Move ansibullbot into ansible/ansibullbot #2 option includes a new combined format, so will be an update to what ansible/ansible provided in 2.9 (and possibly what ansible-base would have for 2.10+)
• any links added to ACD should be for the collection version in ACD, not the latest collection version, which could be more recent
• and the final fallback - no link at all if the collection owner doesn't follow the recommended approach, doesn't provide a link in a programmatically retrievable fixed location, and doesn't manually add their link to the ACD changelog (perhaps in a separate manual link file).
• From a collection owner's perspective: I can provide changelog fragments in the ansible/ansible format, which get automatically amalgamated and published in the ACD changelog. If I don't want to do that, I can provide the output of my changelog process in a defined format, which gets automatically published in the ACD changelog.
• If I don't want to do that either, I can provide a link to my changelog, wherever I publish it (including GitHub). And if I don't do any of the above, ACD shows a "no entry available" for my collection in the changelog.

how to extract ansible changelog generator

• this is Ansible's changelog generator: https://github.com/ansible/ansible/blob/devel/packaging/release/changelogs/changelog.py
• this should most likely be pulled out of ansible-base into its own package
• • continue the to package or not to package discussion next week

ACD Changelog usability

• options for ACD output - a section per collection and whatever we have available in that section (changelog in usable format or a link or nothing). Alternately, we could leave all the links to an end section. That would work better for allowing manual link additions
• we could try out the output options on community.general and/or some of the network collections that may have changelog need before ACD releases.
• 👍 try a manual mockup of what we want the end result ACD to look like and review that
• experiment with pandoc conversions

Felix's PR

• Extend dev guide for collection testing and collection hacking ansible#68899

Actions

@felixfontein play around with the changelog tool from ansible/ansible,
@acozine to review the PR later today

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-04-14/documentation_working_group_aka_dawgs.2020-04-14-14.32.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-04-14/documentation_working_group_aka_dawgs.2020-04-14-14.32.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-04-14/documentation_working_group_aka_dawgs.2020-04-14-14.32.log.html

[felixfontein]

• Extend dev guide for collection testing and collection hacking ansible#68899

[samccann]

2020-04-21

changelog mockup

• ACD changelog mockup is at https://github.com/samccann/ansible/blob/test-changelog/docs/docsite/rst/changelog_acd.rst
• hacked together from a couple of existing collections, based on the ansible/ansible changelog.py script
• https://github.com/felixfontein/community.general/blob/changelog-1.0/changelogs/config.yaml
• the output headings are set in https://github.com/felixfontein/community.general/blob/changelog-1.0/changelogs/config.yaml so we can modify them as needed
• the ansible/ansible Major Changes was reserved for core changes. We can reuse that category in collections for 'something else"

changelog generator -wip

• felixfontein has a WIP of what the changelog-generator tool might look like at https://github.com/felixfontein/ansible-changelog/
• generated output for community.general is at https://github.com/felixfontein/community.general/blob/changelog-1.0/changelogs/CHANGELOG-v1.rst
• and in yaml format at - https://github.com/felixfontein/community.general/blob/changelog-1.0/changelogs/changelog.yaml
• this WIP creates the same changelog as ansible's tool for 2.9 does and can do changelogs for collections
• collection owners who choose not to use the recommended changelog-generator tool would have to convert their output to the yaml file example included above. That is likely what some future ACD changelog tool would look to pull into an ACD changelog

porting guides for ACD and collections

• we could potentially use 'major_changes' for porting guide entries in collections
• and include removals and deprecations
• consider adding 'behavior_changes' to the default config to cover the important changes where a user must do something different when using this new version of a collection/ACD
• then 'major_changes` can remain to describe major new features in a collection or ansible-base
• module X has this new feature" is a "major change" and "module X now requires parameter Y" is a "behavior change

open floor

• agenda items are always welcome, just add a comment to DaWGs (Documentation Working Group) Meeting Agenda 2020 #521
  Actions

---

@need to guestimate what it would take to convert a reno or towncrier to changelog.yaml format
@samccann to follow up with dmellado on how to get reno output into changelog.yaml format

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-04-21/docs_working_group_aka_dawgs.2020-04-21-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-04-21/docs_working_group_aka_dawgs.2020-04-21-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-04-21/docs_working_group_aka_dawgs.2020-04-21-14.31.log.html

[samccann]

2020-04-28

changelogs for ACD

• ACD live mockups based on felixfontein's scripts - https://github.com/felixfontein/ansible-changelog/blob/master/acd/acd.rst
• ACD mockup with ACD version as first header - https://github.com/felixfontein/ansible-changelog/blob/master/acd/acd2.rst
• this is controlled by a config file - https://github.com/felixfontein/ansible-changelog/blob/master/acd/acd.yml
• [RESOLVED] Versioning and deprecation ansible-collections/overview#37
• still need details on how collections will be versioned, especially from a git branching point of view. That's a dependency on finishing the changelog scripts/processes.
• the collection changelog .yam format (looks like this: https://github.com/felixfontein/community.general/blob/changelog-1.0/changelogs/changelog.yaml as opposed to ansible 2.9 one: https://github.com/ansible/ansible/blob/stable-2.9/changelogs/.changes.yaml) contains the contents of the changelog fragments, and contains more info on the new plugins/modules
• 2.9 yaml only contains their names, collection one contains also short desc and namespace
• would be good if the formats could get more aligned (I don't mind the changelog fragments being separate files, but the missing additional info on the plugins is painful) - would also be good if there aren't 2 different changelog generators, but one that can handle both ansible-base and collections.
• possible categories in the changelog - Security Fixes, Breaking Changes/Porting Guide, Major Changes, Minor Changes, Deprecations, Removals, Bugfixes - will need clear guidance on what goes in each category.
• goal is that ansible-base would not have to change anything to start using the new changelog tool
  Actions

---

@felixfontein to try and kickstart that branching etc conversation
@samccann to draft the changelog process as we know it so far into a

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-04-28/docs_working_group_aka_dawgs.2020-04-28-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-04-28/docs_working_group_aka_dawgs.2020-04-28-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-04-28/docs_working_group_aka_dawgs.2020-04-28-14.31.log.html

[samccann]

2020-05-05

checking in about changelogs

• [?w] changelog process for collections ansible-collections/overview#18
• Ansible-maintained content team considering reno with added work to produce the changelog.yml that felix's work requires.
• felixfontein wrote up a spec for the changelog.yaml format (https://github.com/ansible/ansible/blob/devel/packaging/release/changelogs/changelog.py) and added a linter for changelog.yaml files to the generator
• felixfontein also prepared a WIP PR to replace ansible's changelog generator with it: Use antsibull-changelog instead of packaged changelog generator ansible#69313
• https://github.com/ansible-community/ansibulled
• mock collection to experiment with changelog generator - https://github.com/felixfontein/ansible-versioning_test_collection
• https://www.irccloud.com/pastebin/MVT9chqV/
• updated ACD changelog generator WIP hack: https://github.com/felixfontein/ansibulled/tree/acd-changelog/acd_changelog with result: https://github.com/felixfontein/ansibulled/blob/acd-changelog/acd_changelog/acd.rst

docs pipeline update

• The collection downloading and generation of rst from those collection files will live in ansibulled: [WIP] Adding docs ansible-community/antsibull-build#5
• The idea is that this will be usable for both the docs pipeline and external collection authors who want to build docs for just their collections.
• new collections pipeline will be split into two parts, the ansibulled part mentioned above, which generates rST from plugin docstrings, and the Sphinx (rST-to-HTML) part
• collections owners can use ansibulled-docs to generation rST from their plugin docstrings
• 👍 would be good if ansibulled-docs also outputs index.rst files. Will be handy if/when scenario guides are moved into collections /docs folder and pulled back to docs.ansible.com

ansible_metadata

• https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#ansible-metadata-block defines the format
• https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#ansible-metadata-block defines the format
• collection routing ansible#67684
• collections meta/routing.yml handles module deprecation in a collection
• validate-modules: deprecated modules in collections ansible#68646
• supported_by metadata seems to no longer serve a purpose. TBD on whether collection owners/core still want status field in the metadata (stable vs preview etc)
• in summary - ansible-base is phasing out ANSIBLE_METADATA entirely, collections 'may' still want to use the status field but we need to followup to see if that's true
• collection meta/routing.yml should be the source of truth for deprecation/removed and we can move any other status needs into an optional DOCUMENTATION field
• consider ignoring ANSIBLE_METADATA entirely when building collection docs

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-05-05/docs_working_group_aka_dawgs.2020-05-05-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-05-05/docs_working_group_aka_dawgs.2020-05-05-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-05-05/docs_working_group_aka_dawgs.2020-05-05-14.31.log.html

[samccann]

2020-05-12

removing ansible_metadata

• collections tracking issue - Remove use of ANSIBLE_METADATA in collection modules ansible-collections/overview#57
• ansible-base issue - starting metadata sunset ansible#69454
• ansible metdata has two fields, neither of which seem necessary in the new world order
• 👍 remove ANSIBLE_METADATA field entirely
• NOTE - a later decision in this meeting removed this decision <+1: create a documentation field for status, default is NULL and will not show up in output (docs or Galaxy/AH). Developer set their preferred default in a doc_fragment (preview or stable).>
• whatever we decide, galaxy, AH, docsite, and ansible-doc will have to change... and likely docs pipeline and doc generation changes too
• move discussion to New module/plugin documentation fields proposals#68
• 👍 ANSIBLE_METADATA gets dropped entirely, and no immediate replacement for STATUS

version_added

• 👍 for new features in the module docs, version_added should refer to the collection version moving forward

Actions

@- need to test if a module status setting overrides the doc_fragment
@- samccann to comment on ansible-collections/overview#57 with link to
ansible/proposals#68 to continue the discusison

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-05-12/docs_working_group_aka_dawgs.2020-05-12-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-05-12/docs_working_group_aka_dawgs.2020-05-12-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-05-12/docs_working_group_aka_dawgs.2020-05-12-14.31.log.html

[felixfontein]

• Improve the changelog-how-to documentation. ansible#69268 (including a discussion on how version numbers should be documented that are cross-collection; see also https://github.com/ansible/community/wiki/Version-numbers-for-documentation-deprecation-removal-in-the-collection-world and @abadger's ideas on doc schema)

[samccann]

2020-05-19

docs pipeline update

• ansible-doc can't solve what the docs pipeline needs so developing a separate parser with a docs schema. See https://gist.github.com/abadger/5d7ad556052758993b3245f9dc14a1d9 for work thus far
• this is using pydantic for the schema. fyi docs sanity test uses volumptuous
• json schema from this may be helpful in the future for developing stricter testing on the module docs.
• this approach would mean we no longer use ansible-doc --json to output docstrings for module/plugin docs

version_added in collections

• [WIP] ansible-test: allow version_added tests for collections ansible#69291

• [WIP] ansible-test: allow version_added tests for collections ansible#69291

• problem occurs when a collection includes a doc_fragment from ansible-base. The collection has version_added for collection version, while doc_fragment reflects ansible-base version

• [WIP] ansible-test: allow version_added tests for collections ansible#69291 (comment) contains examples of how this looks with ansible-doc

• collections will use version_added to reflect collection version. ansible-base use it to reflect ansible-base version. The PR then parses to add 'built in' vs 'collection' to the version number to clarify for users. (and tests collection version # )

• specify --collection-version_added for ansible-test sanity to enforce new options get version_added set correclty

• how optional should the optional test be and can we turn on the version_added test on ansible-base withought messing up other optional tests?

Actions

@abadger1999 to archive ansible-doc cards in the project board
@samccann to create a 2.11 column for evaluating next steps with this
@samccann to add card to docs pipeline board for future work - consider

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-05-19/docs_working_group_aka_dawgs.2020-05-19-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-05-19/docs_working_group_aka_dawgs.2020-05-19-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-05-19/docs_working_group_aka_dawgs.2020-05-19-14.31.log.html

[bcoca]

• Moving this repo under ansible or ansible-community bcoca/collection#3 (punted from core meeting)

[samccann]

05-20-2020 Supplemental Docs Working Group (DaWGs)

Meeting summary

• changelogs in collections/ACD (acozine, 15:07:56)

  • changelogs summary:
    [?w] changelog process for collections ansible-collections/overview#18 (acozine,
    15:08:42)
  • some docs for the changelogs -
    https://github.com/felixfontein/ansibulled/blob/changelog-docs/docs/changelogs.rst
    (samccann, 15:13:14)
  • felixfontein Felix Fontein -community.general, community.network,
    community.crypto and community.internal_test_tools now validate
    changelog fragments (samccann, 15:14:33)
  • example of a changelog generator config - community.general:
    https://github.com/ansible-collections/community.general/blob/master/changelogs/config.yaml
    (samccann, 15:16:20)
  • those 4 repos use use this extra sanity test runner:
    https://github.com/ansible-collections/community.internal_test_tools/tree/master/tools
    (samccann, 15:17:03)
  • AGREED: need to move
    https://github.com/felixfontein/ansibulled/blob/changelog-docs/docs/changelogs.rst
    into a PR for collections dev guide on docs.ansible.com/ansible
    (samccann, 15:22:10)
  • issues with ansibulled as a tool name - can't use ansi for
    command completion anymore. but ansible-changelog etc creeps into
    the tool names that the core team may want to keep control of
    (samccann, 15:33:54)
  • ACTION: - think up naming options to replace ansibulled-xxx. ac-xxx
    is one option but command completion will be important as well as
    ease of remembering (samccann, 15:44:41)
  • AGREED: collections tools will be renamed ac-* unless we can come
    up with a more interesting pattern that still preserves autocomplete
    for the main ansible tools (acozine, 15:44:54)
  • LINK:
    https://github.com/ansible-collections/community.general/blob/master/changelogs/config.yaml
    (felixfontein, 15:47:44)

• porting guides in the collections ecosystem (acozine, 15:50:15)

  • ACTION: felixfontein will add trivial to the changelog generator
    (abadger1999, 16:01:31)

• open floor (acozine, 16:04:18)

Meeting ended at 16:09:17 UTC.

Action Items

• • think up naming options to replace ansibulled-xxx. ac-xxx is one
    option but command completion will be important as well as ease of
    remembering
• felixfontein will add trivial to the changelog generator

Action Items, by person

• felixfontein
  • felixfontein will add trivial to the changelog generator
• UNASSIGNED
  • • think up naming options to replace ansibulled-xxx. ac-xxx is one
      option but command completion will be important as well as ease of
      remembering

[samccann]

2020-05-26

changelogs in a collections ecosystem

• [?w] changelog process for collections ansible-collections/overview#18 is the tracking issue
• implemented a trivial category (which isn't shown in the generated .rst file; useful if f.ex. a collection wants to have a changelog fragment with every PR
• felixfontein also implemented support that you can use the tool when galaxy.yml isn't there (you'll have to provide more parameters via command-line arguments)
• this work is in https://github.com/ansible-community/ansibulled now
• documentation: https://github.com/ansible-community/ansibulled/blob/master/docs/changelogs.rst https://github.com/ansible-community/ansibulled/blob/master/docs/changelog.yaml-format.md
• what's left to do on this - more people testing/using it - first get it on pypi for easy install, and settle on the naming convention for these tools

naming for the new docs build tool

• https://github.com/ansible-community/ansibulled/wiki/Naming-things-is-hard
• https://github.com/willyg302/antsy
• https://github.com/adamkpickering/antsy-bull - A configuration management (and more) framework with all the benefits of Ansible and none of the drawbacks
• 👍 we will use something like antsy-bull/antsibull - to be discussed/decided later

porting guides

• automating porting guide for 2.10 from changelog fragments is a stretch goal, but not committed to it yet. need to determine complexity of rst embedded in a changelog fragment etc
• Community Working Group Meeting Agenda #539 in case anyone is interested
• 👍 we will have a supplemental DaWGs meeting at 10AM ET on Thursday this week
  Actions

---

@samccann to add 'what do we need to move issues/prs for docs' to Thursday's agenda

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-05-26/docs_working_group_aka_dawgs.2020-05-26-14.30.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-05-26/docs_working_group_aka_dawgs.2020-05-26-14.30.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-05-26/docs_working_group_aka_dawgs.2020-05-26-14.30.log.html

[samccann]

05-28-2020 Agenda Supplemental DaWGs meeting 10am ET

• What docs do we need for 'What do contributors need to know when issues/prs are moved to a new repo'

• Improve the changelog-how-to documentation. ansible#69268

• porting guide strategy

• Followup on changelog strategy - [?w] changelog process for collections ansible-collections/overview#18

• update on docs pipeline

• version_added tests [WIP] ansible-test: allow version_added tests for collections ansible#69291

• new documentation fields proposal New module/plugin documentation fields proposals#68

• Moving this repo under ansible or ansible-community bcoca/collection#3 (punted from core meeting)

• Status updates

• Open Floor

interesting links

• ansible Base (covering all the user/developer guides etc)

• Ansible-maintained collections - what needs to happen in docs for these collections.

• docs pipeline - the work and dependencies to getting module docs from collections back onto docs.ansible.com/ansible.

• Docs issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs

• Docs PRs needing reviews/merges - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs

[samccann]

ansible/ansible#69727 - module deprecation vs meta/runtime.yml

[samccann]

Supplemental DaWGs Meeting - Thurs Nov 5 at 9:30am ET

supporting independent release cycles for ansible-base and ansible in

• problem statement - Ansible pypi package called 2.11 will release in jan/feb? and some time after that, ansible-base will release with a version called 2.11 (but a different 2.11)
• https://etherpad.opendev.org/p/ansible-documentation-split
• we may see more community users installing just ansible-base and the selection of collections they are interested in.
• possible solution: one publication pipeline takes docs content in each maintained stable branch of ansible/ansible and publishes it as docs.ansible.com/ansible-core (or ansible-base . . . exact name TBD); a separate publication pipeline takes docs content from a specific maintained stable branch of ansible/ansible and combines it with specific versions of collections and publishes it as docs.ansible.com/ansible
• this solution would let us maintain a single source for documentation of core/base features that appears in versioned HTML for both the ansible PyPI package and ansible-core or ansible-base
• we may need to pull the docs publishing files out of ansible/ansible - such as theme, scripts to build config.rst, etc etc.
• ansible-base users/developers essentially need everything that doesn't document something that isn't part of ansible-base (i.e. some filters and scenario guides)
• show keyword documentation in ansible-doc ansible#72476 <= jic someone wants to poke
• The Problem: soon there will be an ansible package version 2.11; some time after that there will be an ansible-base/core/engine version 2.11; current documentation cannot handle documenting any features that exist in ansible-base/core/engine 2.11 but NOT in ansible 2.11
• The Opportunity: as we think about how to handle this situation, we can (and should) think about documentation personas - who will be using ansible package 2.11, and what do they need? Who will be using ansible-base/core/engine 2.11 and what do they need?
• 👍 - next step - take a stab at 2-4 personas and the top 5 tasks we think they need in docs (ignoring current docs). That will help us know if we have a two-way split or more ways to split the current docs
• 👍 we will meet at 10:30am ET on Thursdays to discuss the docs split for a few weeks
• https://etherpad.opendev.org/p/ansible-documentation-split is the scratchpad of ideas. Please add your thoughts there as well between meetings
• https://hackmd.io/uKhHRhFUStG_bVNhY10cLQ?both
• gundalows scratchpad for personas - https://hackmd.io/uKhHRhFUStG_bVNhY10cLQ?both

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-11-05/documentation_supplemental_working_group_meeting.2020-11-05-14.42.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-11-05/documentation_supplemental_working_group_meeting.2020-11-05-14.42.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-11-05/documentation_supplemental_working_group_meeting.2020-11-05-14.42.log.html

[samccann]

2020-11-10

opening chatter

• agenda DaWGs (Documentation Working Group) Meeting Agenda 2020 #521 (comment)

version split and supplementary meeting

• Thurs supplemental meeting minutes from last week - DaWGs (Documentation Working Group) Meeting Agenda 2020 #521 (comment)
• weekly Thurs supplemental meeting starts 10:30am ET on #ansible-docs to cover splitting the docsite
• folks are getting confused between ansible-base and Ansible (the names are too similar) -someone somewhere might want to consider renaming one of them

removing docs files from Ansible tarballs

• need to be careful on naming the docs package so no one confuses it with ansible-doc the cli command
• https://en.wikipedia.org/wiki/AsciiDoc
• rst were included in main tarball, we used to have downstream packagers generate htmls and the afformentioned 'ansible-docs' packages
• 👍 we'll build an ansible-documentation package so the documentation is available to those who want it but the main ansible package stays slim; when the time comes we'll build an ansible-core-documentation package also
• first step would be to build the documentation package, get it published with new releases, and only then kick out docs from the existing package

sphinx extension

• there's a PR in the antsibull repository for the sphinx plugin: Add sphinx_antsibull_ext Sphinx extension ansible-community/antsibull-build#210

extending collection docs

• https://github.com/ansible-collections/ansible.utils/tree/main/docs
• existing filter/test plugins can contain multiple different plugins in one file .. so the ansible.utils approach won't help
• roles argspec is wip. see ansible-doc role arg spec support ansible#72120 ... might be more prs
• https://www.youtube.com/ansible-community
• https://github.com/sensu/sensu-go-ansible/blob/master/roles/install/README.md for example.
• • there are competing needs/wants from a collection /docs folder.
• it would probably help to involve all that are currently working on docs of some kind - galaxy, ansible.util, roles argspec, bcoca's branch, antsibull-docs
• who/what will consume the files within a collection /docs folder? AH/galaxy-ng? docs.ansible.com in the future? ...gasp...access.redhat.com?
• • what's the timeline for getting fitler/test plugins documentable and working with ansible-doc and how does this relate to wha ansible.utils is doing in their Dec release?
• what is the timeline for the roles argspec and does it solve all the roles documentation needs, or will roles also want manually written docs within a collection /docs folder (and thus need subfolders which aren't supported today?
• can we also support other manual docs, like scenario guides in the collection /docs folder etc?

Actions

• @samccann to followup on docs problems with ansible.utils - hey use something that is similar to module/plugin docs, but not officially defined by ansible-base, like https://github.com/ansible-collections/ansible.utils/blob/main/plugins/test/validate.py
• @bcoca to post link to his WIP PR for docs in any plugin type (filters/tests etc)

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-11-10/documentation_working_group_aka_dawgs.2020-11-10-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-11-10/documentation_working_group_aka_dawgs.2020-11-10-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-11-10/documentation_working_group_aka_dawgs.2020-11-10-14.31.log.html

[felixfontein]

Idea for improving collection docs

Right now, the per-collection docs are rather limited. They are basically a list of all plugins: https://docs.ansible.com/ansible/latest/collections/community/general/ with details per plugin. There are no further information, like general usage information (more important for other collections than for c.g), scenario guides (which currently reside in ansible/ansible, which doesn't feel right anyway), and also some content is not documented at all, namely test and filter plugins (which are undocumentable right now) and roles.

It would be nice if collections could add docs files that would be included in the docsite.

How about allowing collections to include some .rst files in docs/, and to include them in the docs site build? And to be able to insert links to (some of) these in their main index page (https://docs.ansible.com/ansible/latest/collections/community/general/ for c.g)?

[felixfontein]

• Clarify collection paths in docs ansible#72510

[samccann]

2020-11-12

Personas

• first thoughts on personas - https://etherpad.opendev.org/p/ansible-documentation-split
• not a clear boundary between 'users' and 'creators' in this sense. some places will hand a user a playbook and tell them to write their own inventory. Other places the user is the creator as well.
• one option for 'release independent' developer guides - put all the version-specific information in one guide. So 'in ansible-base...do this... in ansible-core.2.11, do this other thing, etc.
• Community guide and much of the developer guide content could be release-independent
• testing info in the dev guide might be core-specific and we'd need a separate testing section for collection developers etc

release dependent vs independent docs

• we have started maintaining some pages only in devel and stubbing out the info in older versions. release and maintenance, porting guides..
• https://docs.ansible.com/ansible/devel/dev_guide/ (https://github.com/ansible/ansible/tree/devel/docs/docsite/rst/dev_guide)
• https://docs.ansible.com/ansible/latest/community/
• consider one dev guide, with separate 'chapters' for Ansible developer vs ansible-core developer. Same with user-creater personas - not separate books, but separate sections within a book for example

Next Steps

• our goal for the ansible vs ansible-core split is to have a non-versioned docs-set for developers alongside existing versioned docs, with content that starts to explain the differences
• next steps - create a proposed TOC etc for next week's discussion
• Tentative schedule for 2.11: https://hackmd.io/y7BBcweNR3aRVLuMbKkDxw

Actions

• @gwmngilfen and acozine to work on the docs survey

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-11-12/documentation_working_group_supplemental.2020-11-12-15.30.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-11-12/documentation_working_group_supplemental.2020-11-12-15.30.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-11-12/documentation_working_group_supplemental.2020-11-12-15.30.log.html

[samccann]

2020-11-17

removing rst files from tarballs

• some package tarballs contain everything - e.g. should be an editable body of code if someone wanted to base a patch on it
• need to consider that as well as licensing/legal implications of removing docs etc from ansible tarballs
• size of tarball may also be slowing down installation times...
• cannot use wheel option because ansible-core and thus Ansible have setup.py dynamics. See Wheel support for linux aarch64/x86 ansible#71992 (comment)

docs user survey

• draft docs survey for review - https://hackmd.io/JemYBo_8QbqqO9cULo3rJQ

follow up on long-running items

• the sphinx extension is now part of antsibull
• roleargspec PR - ansible-doc role arg spec support ansible#72120
• https://github.com/ansible/ansible/pull/72120/files#diff-96c4675726c535de24f519c4d5f49737a9fb0d184e166786e02b7033ae8ca0b0

open floor

• looking for docs feedback on c.g changes - (a) announcing a new location for content ([stable-1] Add information on docker module migration ansible-collections/community.general#1303) and (b) removing the old content (Removal of docker content for 2.0.0 ansible-collections/community.general#1304)
• anyone can add an agenda item for this meeting by putting a comment on DaWGs (Documentation Working Group) Meeting Agenda 2020 #521
• we currently have an additional meeting on Thursdays, starting one hour later than the regular DaWGs meeting, to focus on splitting out the ansible-core docs from the Ansible (package) docs
• the split is necessary because next year we will have two things with version 2.11 - an ansible 2.11 package, and an ansible-core 2.11 version

Actions

• @samccann to followup with abadger on RST files out of the tarballs
• @samccann to again bug abadger to see if we already take anything out of the Ansible package that's part of the collections source

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-11-17/docs_working_group_aka_dawgs.2020-11-17-14.32.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-11-17/docs_working_group_aka_dawgs.2020-11-17-14.32.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-11-17/docs_working_group_aka_dawgs.2020-11-17-14.32.log.html

[samccann]

scratchpad of ideas for supporting non-plugin docs within a collection - https://hackmd.io/pPeMLaFYSt2W8RAqm-ZkXA

[felixfontein]

• Content move: I've created two PRs for community.general for announcing the docker content move ([stable-1] Add information on docker module migration ansible-collections/community.general#1303) and for actually implementing it (Removal of docker content for 2.0.0 ansible-collections/community.general#1304). We should make sure to polish these PRs so they can be used as templates for moving out other content from c.g, c.n and other collections. (For DaWGs, the changelog fragments are the parts of interest :) )

[samccann]

2020-11-19

Creating a separate Ansible Collections Documentation site

• the current proposal - https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
• a hack of what this might look like - http://docs.testing.ansible.com/ansible/devel/
• TL;DR; of the idea is to create a separate 'Ansible Collections Documentation' and move all scenario etc guides over there, plus the collection index. And leave all the 'what is ansible, how to use ansible, etc on the existing site and call it Ansible Core Documentation
• this is in 'interim' solution as there is more work/discussions on creating an improved docs.ansible.com overall. But that is too far out to solve our immediate problem
• if we split the docs - core vs Collections - we also impact search. Today it would be two independent searches
• we have to decide if we duplicate ansible.builtin to Ansible Collections and rebuild for every ansible-base release, how do we handl the folks who upgrade only based on Ansible releases? They won't get the updated ansible-base until the next Ansible release, but the docs will already be on that future ansible-base release
• Public Ansible Project Meeting Agenda - September 2020 #560 (comment) https://meetbot.fedoraproject.org/ansible-meeting/2020-09-29/ansbile_core_irc_public_meeting.2020-09-29-18.58.log.html
• could use pip show for both ansible-core and Ansible but doesn't solve the problem for those who don't install w/ pip
• could say ' pip ... or use the package manager from your OS'
• how to we handle google search when we duplicate docs such as installing and using collections vs cannonical url

Actions

• @samccann acozine - review old old DaWGs meeting minutes and other docs that described decisions when we created the docs pipeline but decided NOT to create a /collections/ url on the docsite
• @- open a docs PR to explain how to determine ansible-base version vs Ansible package version...ansible --version is base, pip show ansible is Ansible version
• @samccann to create pro/con list for the different way forward and/or an outline of which content goes where

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-11-19/documentation_working_group_aka_dawgs_supplemental_meeting.2020-11-19-15.30.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-11-19/documentation_working_group_aka_dawgs_supplemental_meeting.2020-11-19-15.30.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-11-19/documentation_working_group_aka_dawgs_supplemental_meeting.2020-11-19-15.30.log.html

[samccann]

2020-11-24

slimming down the tarballs by removing docs

• Compressed size w/o docs is 28MB vs 29MB today. Installing took 90 sec w/o docs vs 100 sec with
• decision was made that it wasn't worth removing docs from the tarballs at this point.

uses of the collection /docs/ folder

• some ideas about the collections /docs folder etc - https://hackmd.io/pPeMLaFYSt2W8RAqm-ZkXA
• the goal is to allow collection owners to write 'user guide' and more complex examples etc within the collection /docs folder and then render them in either docs.ansible.com or some future galaxy-ng
• we could only include /docs that are explicitly suggested by the collection - e.g. looking ad docs/anstibull.yml file to find rst files to include
• whateve solution we have for collection /docs needs to cover roles, playbooks, as well as any other guides collectoin owners want to create
• would like the collection index to have collection defined: Summary section, auto generated plugin index, links to static content section.
• we should put collection name and collection version onto the collection index page (regardless of how the rest of the page is structured)
• see how puppet does some of this https://forge.puppet.com/modules/puppetlabs/stdlib - with tabs for changelogs, example foler from github etc

docs user survey

• revised user survey draft https://hackmd.io/JemYBo_8QbqqO9cULo3rJQ#
• Sections 1 and 2 should tell us how well our documentation is doing
• Section 3 lets us "slice and dice" the data by different types of users
• feedback deadline is Dec 1 so we can get the survey link into the next Bullhorn

open floor

• please provide feedback by Dec 3 on Separating Ansible 3.0.0 collection docs from ansible-core - https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
• No supplementary meeting on Nov. 26, since it's Thanksgiving Day for the US-based docs team

Actions

• @samccann ask galaxy team what they render today - md/rst and if they look at all in the /docs folder
• @- we need to get involved in how filter/test docs are structured, how the collection /docs folder works, how roles documenttion will work.. many seats... many tables
• @abadger1999 to do a slight mockup of what a new collectoin page could look like

Logs

Minutes: https://meetbot-raw.fedoraproject.org/ansible-docs/2020-11-24/docs_working_group_aka_dawgs.2020-11-24-14.31.html
Minutes (text): https://meetbot-raw.fedoraproject.org/ansible-docs/2020-11-24/docs_working_group_aka_dawgs.2020-11-24-14.31.txt
Log: https://meetbot-raw.fedoraproject.org/ansible-docs/2020-11-24/docs_working_group_aka_dawgs.2020-11-24-14.31.log.html

[samccann]

Summary on ansible.utils - we will not at this point update antsibull to attempt to pull in the static RST files in that repo that covers the filter/test etc plugins. At some point in the near future, ansible-core will have a solution to generate docs from these plugin types, and anstibull will be updated at that time to support the standard solution.

[samccann]

2020-12-01

opening chatter

• DaWGs (Documentation Working Group) Meeting Agenda 2020 #521 (comment)

redirects post 2.10

• https://startpage.com/do/metasearch.pl?query=ansible%20include%20tags
• search results do still return older docs for modules (2.6, 2.3, etc). Can we find a way (robots.txt??) to have search engines ignore EOL pages ?
• people do still replace /2.5/ for /latest/ in the url when they get the wrong version result from google.

open floor

• please review docsite split proposal before Thursday - https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
• supplemental meeting to discuss docsite split happens at 10:30am ET on Thursday

Actions

• @samccann acozine -investigate options to remove EOL pages from all search results (robots.txt??)

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-12-01/docs_working_group_aka_dawgs.2020-12-01-14.30.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-12-01/docs_working_group_aka_dawgs.2020-12-01-14.30.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-12-01/docs_working_group_aka_dawgs.2020-12-01-14.30.log.html

[samccann]

2020-12-03

opening chatter

• draft proposal doc https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both
• hacked ansible-collections docsite: http://docs.testing.ansible.com/ansible/2.11/
• hacked ansible-core docsite: http://docs.testing.ansible.com/ansible/devel/
• hacked docsites will disappear without warning in a few weeks
• The guiding principle here is that the Ansible Collections Documentation includes only the scenario/platform guides specific to those collections, and the overall collection index. Everything else is really based on the version of ansible-core included and is thus in the Ansible Core Documentation.

pros and cons of splitting the docs

• we should duplicate ansible.builtin on both docsites until those plugins are removed from core. Core users will need that info Ansible package docsite updates won't be in sync with core releases.
• consider adding to the core banner for those plugins 'for the full collection index go here' to point to ansible-collections
• consider interim stub pages on ansible-core-2.11 to show where all the scenario etc guides have moved to
• general problems with latest https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both#How-to-handle-latest

handling /latest/

• the /latest/ convention solves the problems of personal/blogpost links going stale. if they link to a /latest/ page, it always stays valid
• make sure any links from ansible-collections to ansible-core docs uses the version specific url, not /latest/ so it matches the core version used w. Ansible
• general feeling so far is to keep /latest/ for both docsites

Actions

• @samccann to discuss moving scenario guide .rst files to ansible-collections somewhere -w gundalow and abadger1999
• @explore generally how much of our current documentation actually needs to be versioned and how versioned and unversioned docs could live together on docs.ansible.com in perfect harmony

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-12-03/dawgs_supplemental_meeting_aka_the_great_docsite_split_of_2021.2020-12-03-15.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-12-03/dawgs_supplemental_meeting_aka_the_great_docsite_split_of_2021.2020-12-03-15.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-12-03/dawgs_supplemental_meeting_aka_the_great_docsite_split_of_2021.2020-12-03-15.31.log.html

[samccann]

2020-12-08

changing meeting time

• for some regular attendees - this current time is problematic. Seems later in the day (ET) would work better
• 👍 DaWGs meeting to move to 16:00 UTC for the winter, revert to 14:30 UTC in spring

formatting for options in module docs

• DaWGs (Documentation Working Group) Meeting Agenda 2020 #521 (comment)
• https://usercontent.irccloud-cdn.com/file/V6uX3I1x/image.png
• IBM style guide would format this as bold for the option and teletype for the value. Using our current format types, this would be B(var)=C(value)

quick updates

• https://www.surveymonkey.co.uk/r/B9V3CDY is the one for the website
• supplemental meeting on Thursday Dec. 10 at 15:00 UTC
• review https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ beforehand if possible
• https://yourcalendricalfallacyis.com/
• https://elekk.xyz/@noelle/99213354254637980

Actions

• @update https://github.com/ansible/community/tree/main/meetings and https://github.com/ansible/community/wiki/Docs to reflect this change
• @dmsimard to draft 5 example renders of options in DaWGs (Documentation Working Group) Meeting Agenda 2020 #521 (comment) + B(option)=C(value) to help vote at a later meeting
• @samccann add survey to ansible banners for latest/devel

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-12-08/docs_working_group_aka_dawgs.2020-12-08-14.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-12-08/docs_working_group_aka_dawgs.2020-12-08-14.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-12-08/docs_working_group_aka_dawgs.2020-12-08-14.31.log.html

[samccann]

2020-12-10 DaWGs Supplemental meeting - docsite split

opening chatter

• Clarify CLI version number as core version ansible#72287
• here is a WIP for "ansible --version" to display both the ansible-core and ansible versions Clarify CLI version number as core version ansible#72287
• can use a combination of ansible --version (to show core version once the pr is merged) and pip show ansible for the Ansible version
• will need a page or paragraph somewhere that says "here's how you tell which versions you have installed"
• symlinks likely will be bad for SEO but generating two versions of the docsite from the same sources could work (along with other limitations)
• Known things that would have to change to maintain good SEO with duplicate content are the /latest/ url and canonical url which is specified in the conf.py
• 👍 We will duplicate user guide on Ansible docs and ansible-core docs with appropriate SEO optimizations

ansible-core docs with no collection index

• while it is not ideal that you can't find anything about networking/cloud/security on the ansible-core docsite, this is an short-term fix until we get to a docsite based on personas and a better way to get between all the information

moving non-plugin collections docs to other repo(s)

• see the section here for an overview - https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ
• and see here for some real detail - https://hackmd.io/pPeMLaFYSt2W8RAqm-ZkXA

where do we publish ansible.builtin docs

• we need to track ansible version as 3.X since it will be one docset to cover 3.0, 3.1, etc (aka semver)
• can we have ansible-3.x', ansible-core-3.0`, etc in the version dropdowns so we have one docsite with both sets of info?
• https://docs.ansible.com/ansible/devel/collections/index.html
• we will need separate conf.py to do all this... tho might be done w/ builder instead of different repos. Intersphinx might help with M() between the docsites some
• need something on ansible-core collection index to say 'go to ansible for much more'

Actions

• @samccann acozine - ask for a way to show the Ansible version along with core version installed
• @samccann to ask internal SEO expert how to handle duplicat content - is cannonical url enough?
• @samccann to discuss ansible-core having its own docsite w/ core team
• @samccann to create better mockups of separate /ansible/ vs /ansible-core docsites for review
• @acozine to create a PR with a page about "figuring out versions"
• @samccan to hack more mockups, maybe play w/ intersphinx

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-12-10/documentation_working_group_supplemental_-_docsit_split.2020-12-10-15.30.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-12-10/documentation_working_group_supplemental_-_docsit_split.2020-12-10-15.30.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-12-10/documentation_working_group_supplemental_-_docsit_split.2020-12-10-15.30.log.html

[felixfontein]

• We're using I(...) for option names (translates to italics) and C(...) for option values (translates to teletype code-style) (ref). For option=value, we are using I(option=value). In modules: fix documentation formatting ansible#72737 (comment) @samdoran wrote that he thinks italics make option=value harder to read instead of using code-style for both. I agree that option=value is not as great as option=value, but I also find option=value not perfect either. My suggestion would be option=value. So maybe we should discuss the following options:
  1. option=value (current)
  2. option=value
  3. option=value
  4. option=value

  In the docs style, it looks like this (with some regular text at the top):

  We also need to discuss how we want to do this.

  1. Adjust documentation manually.
  2. Make docs processing (antsibull-docs) a bit more intelligent, so that I(option=value) is automatically converted.

[felixfontein]

• Add link to all module and plugin indexes ansible#72743 Add links to module index and plugin indexes (1, 2, ...).

[samccann]

2020-12-15

holiday schedule

• 👍 Meetings cancelled Dec. 24, Dec. 29, and Dec. 31
• 👍 Meeting Dec. 22 will happen but will be very informal

Actions

• @abadger1999 to figure out how many formatted entries we have in the ansible docs build

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-12-15/dawgs_aka_docs_working_group.2020-12-15-16.01.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-12-15/dawgs_aka_docs_working_group.2020-12-15-16.01.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-12-15/dawgs_aka_docs_working_group.2020-12-15-16.01.log.html

[samccann]

2020-12-17

mockups ...sort of

• this is a rough mockup of what Ansible 3.x would look like - http://docs.testing.ansible.com/ansible/3.x/index.html
• this is a rough mockup of what Ansible core would look like - http://docs.testing.ansible.com/ansible/2.11/index.html
• the mockup uses 3.x in the url for test purposes as the pipeline currently requires x.y in the version slot

unversioned docs

• can we publish just one release-independent version of the community guide? the developer guide? anything else?
• • do we have the time to create something like docs.ansible.com/contributors - and have community and dev guides there? in time for the Feb Ansible 3.0.0 release

Actions

• @acozine to create an agenda for the first week of January

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-12-17/documentation_working_group_aka_dawgs_supplemental.2020-12-17-15.31.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-12-17/documentation_working_group_aka_dawgs_supplemental.2020-12-17-15.31.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-12-17/documentation_working_group_aka_dawgs_supplemental.2020-12-17-15.31.log.html

[samccann]

12-22 2020 Agenda - NOTE TIME CHANGES TO 11:00 ET

Following agenda is wishful thinking, depending on who is around on Tuesday:

• update on module formatting for option: value

• Add link to all module and plugin indexes ansible#72743 Add links to module index and plugin indexes (1, 2, ...).

• update on collection /docs folder uses

• filter/test plugin docs update

• role argspec update

• update on bitflip process for Ansible release

• what should our redirect policy be post 2.10? Do we continue updating them for moved collections? do we use stub pages, etc? see Script to create docsite redirects ansible-community/antsibull-build#77 (comment)

• new documentation fields proposal New module/plugin documentation fields proposals#68

• Other status updates

• Open Floor

Easy Places you can help!

• Updating docs to use FQCN in collections - DOCS: M() and seealso links in module docstrings should use FQCN  ansible-collections/overview#89
• edits to https://github.com/ansible/ansibullbot/blob/master/docs/collection_migration.md
• all Docs issues
• Docs PRs needing reviews/merges

Less easy but need developer help on:

• improve `ansible-test documentation - Improve ansible-test documentation  ansible#70555

interesting links

• ansible Base (covering all the user/developer guides etc)
• Ansible-maintained collections - what needs to happen in docs for these collections.
• docs pipeline - the work and dependencies to getting module docs from collections back onto docs.ansible.com/ansible.

Logs

Minutes: https://meetbot.fedoraproject.org/ansible-docs/2020-12-22/docs_working_group_aka_dawgs.2020-12-22-16.00.html
Minutes (text): https://meetbot.fedoraproject.org/ansible-docs/2020-12-22/docs_working_group_aka_dawgs.2020-12-22-16.00.txt
Log: https://meetbot.fedoraproject.org/ansible-docs/2020-12-22/docs_working_group_aka_dawgs.2020-12-22-16.00.log.html

[samccann]

01-07-2022 DawGS supplemental - docsite split

• Review the rest of list of problems we have - https://hackmd.io/iDEyihLqRtWnjtOUd3pNYQ

• versioned vs unversioned docs - community guide? developer guide?

• update on moving scenario .rst files to another repo

• Status of proposal https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both

• next steps

[acozine]

Moving the conversation to #579.