15:01:25 <acozine> #startmeeting Docs Working Group aka DaWGs
15:01:25 <zodbot> Meeting started Tue Aug 17 15:01:25 2021 UTC.
15:01:25 <zodbot> This meeting is logged and archived in a public location.
15:01:25 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:25 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:25 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:01:31 <acozine> #topic opening chatter
15:01:33 <acozine> who's around?
15:01:37 <samccann> helloooooo
15:01:45 <acozine> hi samccann!
15:01:49 <acozine> #chair samccann
15:01:49 <zodbot> Current chairs: acozine samccann
15:01:59 * samccann sits in her new comfy chair
15:02:08 <acozine> Mr. Badger is away, as mentioned earlier
15:02:44 <gwmngilfen-work> vaguely here, in anothing mtg tho
15:02:58 <acozine> dericcrago: dmsimard gundalow gwmngilfen-work briantist cyberpear felixfontein lmodemal[m] tadeboro Xaroth you folks chatting docs today?
15:03:14 <acozine> gwmngilfen-work: understood, I won't make you furniture
15:04:04 * dericcrago waves
15:05:25 <acozine> samccann: it might be you and me today
15:05:25 <acozine> the summertime lull
15:05:30 <samccann> "you and meeeee... against the woooorrrld.... sometimes it feels like... you and meeee against the world..."
15:05:39 <acozine> hey dericcrago
15:05:41 <acozine> #chair dericcrago
15:05:41 <zodbot> Current chairs: acozine dericcrago samccann
15:05:43 * samccann channels a bit of old 70s music
15:06:06 <briantist> o/
15:06:06 <briantist> (but running a standup also)
15:06:34 <acozine> hey briantist
15:07:27 <acozine> I won't chair you either for now
15:07:46 <acozine> but ping again if/when you want to be furniture
15:08:05 <acozine> okay, with a small group, I'm going to go rogue on the agenda
15:08:19 <samccann> heh
15:08:23 <acozine> #topic suggestions from the docs user survey
15:08:24 <gwmngilfen-work> ha
15:08:52 <acozine> samccann and I went through the text responses to the docs survey
15:09:11 <acozine> answers to the questions about what was hardest to learn, what would most benefit from improvements, and so on
15:09:25 <acozine> with over 800 responses, just reading them took a while!
15:09:41 <acozine> we compiled a list of ideas and suggestions and complaints
15:09:46 <acozine> and are now creating issues from them
15:10:25 <acozine> all related issues are prefixed `Docs survey feedback`
15:11:06 <acozine> so far I've put them all in ansible/ansible
15:11:11 <samccann> #info docs survey feedback issues opened - https://github.com/ansible/ansible/issues?q=Docs+survey+feedback
15:11:29 <samccann> do we want to add a call for help with those?
15:11:46 <acozine> yeah, maybe especially with the one about filter examples
15:11:51 * acozine looks for that one
15:12:06 <gwmngilfen-work> ooh surveys
15:12:26 <acozine> gwmngilfen-work: yep, we're coming around the bend, toward full circle on the survey
15:12:41 <acozine> #info feedback and help both welcome particularly on https://github.com/ansible/ansible/issues/75507
15:13:39 <briantist> love that idea, that was definitely one of the most difficult parts about learning ansible for me
15:14:13 <acozine> agreed, and examples are the best teachers for complicated things
15:14:30 <briantist> yes agreed, it's so hard to know where the boundaries are in terms of yaml/ansible/jinja and filters that are ansible-specific vs. jinja builtin
15:14:54 <acozine> we can't document all the built-in jinja filters, but we can show examples that use them
15:15:17 <acozine> by far the most common feedback in the survey was "add more examples"
15:16:02 <samccann> i think it was hard to tell in the survey - do we need more/better realworld examples in the modules as well?
15:16:10 <briantist> yes exactly! `selectattr` and `map` for example should not be documented in ansible docs per se, but they end up being the solution to a lot of tricky ansible templating stuff and examples are very helpful. A brief description on what they do/how they work, with links to jinja docs wouldn't be bad either
15:16:13 <acozine> yes, that was part of the survey response
15:16:18 <acozine> samccann: ^^^
15:16:23 <acozine> not just templating examples
15:16:48 <acozine> but we currently don't have any templating examples, really, while we do have at least some module examples
15:16:57 <felixfontein> o/
15:17:01 <samccann> briantist - can you add your ideas to that issue so we don't lose them?
15:17:03 <acozine> hey felixfontein!
15:17:08 <acozine> #chair felixfontein
15:17:08 <zodbot> Current chairs: acozine dericcrago felixfontein samccann
15:17:10 <briantist> yup!
15:17:15 <felixfontein> sorry, was busy trying to set up display via dock for my new laptop :)
15:17:33 <acozine> ooh, shiny new tech!
15:17:38 <briantist> you can chair me now if you want (or not, whichever), am out of my meeting
15:17:45 <acozine> #chair briantist
15:17:45 <zodbot> Current chairs: acozine briantist dericcrago felixfontein samccann
15:18:12 <acozine> does Sphinx support expand/collapse sections?
15:18:24 <acozine> I'm thinking about how to structure these examples
15:18:46 <acozine> thinking we could call it the "Ansible Pattern-Book"
15:18:48 <samccann> I haven't seen anything with expand/collapse in sphinx templates that I've looked at
15:18:50 <briantist> ^ not sure (and great question) but slightly related I found out recently that github does!
15:19:01 <acozine> oh, cool
15:19:08 <briantist> https://gist.github.com/pierrejoubert73/902cc94d79424356a8d20be2b382e1ab
15:19:14 <samccann> oh cool!
15:20:56 <dericcrago> would the examples be similar to what's on https://docs.ansible.com/ansible/latest/user_guide/complex_data_manipulation.html ?
15:21:01 <samccann> #info maybe there is  a way to add expand/collapse to sphinx output so users can more easily expand the examples section - https://guido.vonrudorff.de/2013/sphinx-documentation-collapse-content/
15:21:47 <acozine> dericcrago: yes, that's a start toward a pattern book
15:22:37 <dericcrago> cool, yeah, I've ended up there several times myself
15:23:10 <acozine> that page isn't consistent about showing the output - it would be great to have a consistent pattern
15:23:10 <samccann> #info an example of a good 'pattern' book for examples is https://docs.ansible.com/ansible/latest/user_guide/complex_data_manipulation.html
15:23:12 <felixfontein> samccann: that snippet requires jquery, and might not be very friendly to screen readers
15:23:42 <samccann> #info That particular sphinx expance uses jquery and might not be good on screen readers
15:23:48 <samccann> thanks felixfontein good to know!
15:23:53 <acozine> looks like others have wanted this capability: https://github.com/readthedocs/sphinx_rtd_theme/issues/402
15:24:01 <samccann> #info an example pattern book should also include output
15:25:09 <samccann> #info for expand collapse - see https://github.com/readthedocs/sphinx_rtd_theme/issues/402 for some hints
15:25:31 <acozine> maybe there's a theme somewhere that does this in an accessible way, one that we can copy for the ansible theme
15:26:03 <samccann> we have our own theme now. Shall I open an issue there to see if smarter minds than me know how to do this?
15:26:34 <felixfontein> https://stackoverflow.com/questions/2454577/sphinx-restructuredtext-show-hide-code-snippets/60394068#60394068 might be useful, though it's ugly (on sphinx side)
15:26:39 <briantist> it would be good to look into the one linked; the jquery requirement may be only to implement the expand while fallback always displays the content; as in, it may already work well with screenreaders
15:26:52 <briantist> (I haven't looked at it, just thinking about what might be possible)
15:27:37 <acozine> I saw that same SO post felixfontein - the three answers implement this in JQuery, javascript, and raw HTML
15:27:37 <samccann> #info another useful expand/collapse thread - https://stackoverflow.com/questions/2454577/sphinx-restructuredtext-show-hide-code-snippets/60394068#60394068
15:28:12 <samccann> So we know there may be options.
15:28:21 <samccann> What do we want to expand/collapse on?
15:28:31 <acozine> samccann: I like the idea of filing a ticket on the ansible theme repo
15:28:35 <felixfontein> some sphinx extension which generates <details></details> (with <summary><summary/>) would probably be best
15:28:49 <samccann> #info some sphinx extension which generates <details></details> (with <summary><summary/>) would probably be best
15:29:25 <samccann> #action samccann to open an issue on the ansible theme to ask for expand/collapse capability
15:29:47 <samccann> I think the module/plugin docs would be a great use of this.
15:30:12 <acozine> we could either expand/collapse each code snippet example, or we could divide each example into three parts (data, expression, output) and collapse/expand them separately
15:31:01 <acozine> I'm just thinking about page length, basically - even with a dozen examples, if each one is 40 lines of code, that's a long page
15:31:03 <samccann> acozine - so you are talking in .rst (aka the guides)
15:31:13 <samccann> or the pattern book etc
15:31:21 <acozine> yeah, that's what I was thinking
15:31:40 <acozine> but no reason we couldn't extend the functionality to other pages once we had it working
15:31:42 <samccann> what about module docs? Worth trying there or not really?
15:31:45 <samccann> ok cool
15:32:30 <samccann> #info this would be good on something like the pattern example pages. we could either expand/collapse each code snippet example, or we could divide each example into three parts (data, expression, output) and collapse/expand them separately
15:32:49 <samccann> #info and possibly expand to module docs in the future
15:33:11 <acozine> if we put out a call for examples on social media, I hope we'd get a flood of them
15:33:33 <samccann> cyb-clock-clone sez we are 33 minutes into the meeting and 25 into the current topic
15:34:14 <samccann> We'd want proven working examples, but if we mandate it has to have the output etc, that might be good enuf?
15:34:15 <acozine> sort of a "give us the template expression you're most proud of, or the one that took the most blood-sweat-and-tears to create" request
15:34:37 <samccann> or we put a note at the top of these pages that they are community examples so no guarrantees etc?
15:34:50 <acozine> I think we'd have to test them ourselves
15:34:58 <samccann> is that possible?
15:35:09 <samccann> I mean some sure, but I'd guess some get kinda deep.
15:35:33 <acozine> for template expressions? yes, as long as they are self-contained - if the example includes the data and the expression, we should be able to generate the output
15:35:51 <samccann> ok I was thinking beyond template expressions, but sure
15:36:23 <acozine> module examples could get more challenging
15:36:29 <samccann> an alternative - we could have an /examples/ github repo where community can open a PR with their favs and put them there? Then we could use the existing github expand/collapse?
15:37:04 <samccann> either way we'd want the ability to give them credit, like we do for modules today
15:37:05 <acozine> interesting idea - easier to jump-start, but not as findable
15:37:31 <samccann> it depends on how findable you think our docs are today :-)
15:38:22 <acozine> true
15:38:49 <acozine> okay, do we have any next steps for this project?
15:38:54 <samccann> is it worth putting this on the community meeting agenda? To see which place the community wants to add them?
15:39:01 <acozine> yeah, that's a great idea
15:39:09 <samccann> ok I'll pop over and do that now
15:39:25 <acozine> I'll be out for most if not all of tomorrow's meeting
15:41:36 <acozine> okay, we'll document the idea of expand/collapse on the Ansible sphinx theme repo, and bring up the Pattern Book at the community meeting
15:41:38 <samccann> #action samccann create a topic issue for the community WG on community-contributed examples
15:41:45 <acozine> that seems like good steps forward
15:41:55 <samccann> sounds good
15:41:57 <acozine> we will now return to our regularly scheduled agenda ;-)
15:42:01 <samccann> heh
15:42:36 <acozine> #topic sphinx redirects
15:43:01 <acozine> https://github.com/ansible/ansible/pull/75502/files is a WIP PR that uses Sphinx for redirects instead of apache config
15:43:18 <acozine> samccann: this is really cool!
15:43:19 <samccann> I haven't tried anything with wildcards yet etc.
15:43:36 <acozine> but it works for basic 1:1 page redirects?
15:43:37 <samccann> so I don't know how flexible it is
15:43:39 <samccann> yep
15:43:44 <samccann> with a bit of experimenting ;-)
15:43:48 <acozine> heh
15:44:05 <acozine> the great thing about putting our redirects in Sphinx is that they would be visible to the community
15:44:08 <samccann> so the question becomes - how far do we want to go with this? It's still a 0.1 release
15:44:12 <acozine> which the apache redirects are not, currently
15:44:16 <samccann> true
15:44:46 <acozine> hm, so maybe we see what's needed to get it to 1.0 and see if we can contribute?
15:44:56 <samccann> #info this PR proves it works for simple 1-1 redirects and would make the redirects visible to the community
15:45:22 <acozine> where's the repo for the extension?
15:46:21 * gundalow waves
15:46:27 <acozine> hey gundalow
15:46:30 <acozine> #chair gundalow
15:46:30 <zodbot> Current chairs: acozine briantist dericcrago felixfontein gundalow samccann
15:46:42 <samccann> #info redirects extension is https://pypi.org/project/sphinx-reredirects/
15:47:11 <samccann> huh it's in gitlab --)
15:47:14 <samccann> #link https://gitlab.com/documatt/sphinx-reredirects
15:48:57 <acozine> heh, not just redirects, but reredirects
15:49:17 <samccann> oh the number of times that got me...
15:49:20 <samccann> there's another one - https://github.com/sphinx-contrib/redirects
15:49:21 <acozine> heh
15:49:23 <acozine> I bet
15:49:37 <acozine> yeah, the sphinx-contrib one was last touched in 2017
15:49:41 <samccann> but hasn't been touched yeah
15:50:16 <acozine> the one nice thing in that one is, it uses a separate file instead of putting the redirects directly into the config
15:50:44 <acozine> but that seems easy to recreate (rerecreate?) if the newer extension doesn't already support it
15:50:52 <samccann> heh
15:51:07 <samccann> there's also this blog post - https://tech.signavio.com/2017/managing-sphinx-redirects
15:51:42 <samccann> but the gist of it all - we have options, we can experiment further and decide how much we want to move to a sphinx-based redirect solution
15:51:52 <acozine> awesome
15:51:56 <acozine> nice work samccann!
15:52:05 <acozine> yikes, less than ten minutes left
15:52:14 <samccann> #link https://tech.signavio.com/2017/managing-sphinx-redirects
15:52:18 <acozine> time for an open floor
15:52:41 <acozine> #topic open floor
15:52:45 <dericcrago> I have something
15:52:49 <acozine> dericcrago: cool!
15:53:16 <briantist> I also have something (will type a bunch while Deric goes 😁)
15:53:36 <acozine> excellent!
15:54:35 <dericcrago> while sifting through the PPA download stats I always wondered why ubuntu 14.04 (trusty) was always like the 2nd most downloaded for every ansible release and then https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-debian was pointed out to me
15:55:07 <acozine> heh, how old is trusty?
15:55:21 <acozine> 7 years
15:55:28 <acozine> could use some updating . . .
15:55:30 <dericcrago> ubuntu is calver so 14.04 is April, 2014
15:56:10 <dericcrago> yeah, ubuntu versions map to debian versions, so I really think there should be a table
15:56:15 <samccann> so is it as simple as replacing trusty with calver?  or should we say something like pick the name of the current ubunter versions?
15:56:22 <acozine> that page in particular gets out of date very quickly
15:56:33 <samccann> yeah what she said
15:56:48 <acozine> I wish we could recruit some folks from each distro who'd be willing to update that page for each release
15:56:54 <samccann> it's also a difficult page now because some distributions pull in the package and some only core (and some neither  I think)
15:56:56 <dericcrago> would it be easier to point directly to the PPA and have the instructions maintained there?
15:57:14 <samccann> do you have a sample pointer you are talking about?
15:57:26 <acozine> if the PPA already maintains instructions, that would be great
15:57:50 <samccann> #info install instructions for debian are woefully outdated (trusty is old, calver is newer) - https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-ansible-on-debian
15:57:52 <acozine> if not, we'd just be shifting the challenge to a less-visible (to me, at least) place
15:58:05 <dericcrago> it doesn't really, but I was thinking maybe it could get jammed into the description - https://launchpad.net/~ansible/+archive/ubuntu/ansible
15:58:42 <acozine> current LTS for ubuntu is 20.04 “Focal Fossa,”
15:59:05 <samccann> dericcrago - do we (ansible team) maintain that page?
15:59:28 <samccann> if so, jamming it in the description might help
15:59:34 <dericcrago> yes, I have been lately
16:00:02 * dericcrago < https://libera.ems.host/_matrix/media/r0/download/libera.chat/7e35f2f92ea3844b184705c5f1f2f053df59ffc7/message.txt >
16:00:06 <felixfontein> /4/4
16:00:26 <samccann> maybe what we need is to have you and others more 'in the know' take a good long look at that install page and advise us on the best way to handle it since it's not one ansible release anymore?
16:00:48 <dericcrago> so you could work backwards from your debian version to know which ubuntu version you wanted to pin for the PPA
16:01:22 <samccann> cyb-clock-clone sez we are at the top of the hour
16:01:47 <samccann> #info on ubuntu vs debian releases https://libera.ems.host/_matrix/media/r0/download/libera.chat/7e35f2f92ea3844b184705c5f1f2f053df59ffc7/message.txt
16:01:57 <acozine> I suspect that the reason so many folks install that version is that they're copying/pasting . . . and they may be new enough that they need copy/paste instructions
16:02:17 <samccann> so next steps are?
16:02:35 <samccann> either we update that section, or dericcrago adds more to the description and then we just point to that?
16:02:54 <acozine> I'd say updating is the more new-user-friendly option
16:03:06 <acozine> but it's also more work, and it obviously hasn't happened up to now
16:03:14 <samccann> ok. dericcrago can you open a docs issue on ansible/ansible with the details pls?
16:03:16 <dericcrago> I can take a stab at both over the next week and see what everyone thinks next meeting?
16:03:20 <samccann> or a direct PR if you are up for it
16:03:22 <acozine> dericcrago: that sounds great
16:03:25 <samccann> cool!
16:03:44 <samccann> #acton dericcrago to open a PR to update the debian install instructions
16:03:51 <samccann> heh
16:03:54 <acozine> thanks for bringing that to the DaWGs dericcrago
16:04:02 <briantist> still time for a quick update from me?
16:04:04 <samccann> #action dericcrago to open a PR to update the debian install instrtuctions
16:04:06 <acozine> briantist: sure
16:04:13 * samccann will not fix her spelling error!
16:04:15 <briantist> The next things I want to add to my docs build stuff: felixfontein 's suggestion of showing the differences is something I want to do. Since I'm now building both versions of the docs, I can do a `git diff` on the results, and then I can post the results in the PR with GH's diff highlighting. This is actually why I looked into the expand support!
16:04:24 <briantist> I realized that there could be unexpected docs changes when you didn't intend to, and the primary reason for that would be a PR that needs to be rebased. Showing the diff would further help clarify what differences there are when you don't expect any. Second problem is that if your PR has docs changes, then you update it so it doesn't anymore, the published site and the PR comment never go away, so I want to address that too. (these
16:04:24 <briantist> things are planned changes, haven't started them, but they seem doable).
16:04:35 <briantist> Finally, I still want to contribute this stuff back in some meaningful way, but again it may be a little too opinionated to be put in the collection template, so I wonder if the best first step for that is to work directly with some collection owners who want to implement some or all of this, and see what shakes out that generalizable. If anyone here is up for that (not imminently but, at some point), please let me know.
16:04:35 <dericcrago> sure, thanks everyone!
16:05:42 <samccann> great stuff briantist!
16:06:14 <samccann> would be good to bounce it off a couple of other collection owners for sure. Maybe you can find some volunteers at tomorrows (or some future) community meeting?
16:06:41 <acozine> briantist: the diff capability sounds useful, and yes, picking a collection (or a few collections) to test it on sounds great
16:07:14 <acozine> #info briantist looking for collection maintainers to collaborate on docs build enhancements
16:07:37 <briantist> cool, I'll put a call out during a community meeting when I'm closer to being able to act on it (a little busy at the moment) and after I tighten it up a bit (the diff support, and the changes supporting removal of changes, if that makes sense haha)
16:07:52 <acozine> sounds good, no rush
16:08:23 <acozine> thanks for working on that code, and for bringing the idea to the DaWGs
16:08:25 <samccann> do we have a way today to generate the collection docs locally at the PR stage?
16:08:35 <briantist> in my collection, yes :)
16:08:38 <samccann> or prior to PR etc. if so we should document that somewheres
16:08:54 <samccann> HAHA ok ok. I lost track of whether something was added to antsibull to do that
16:09:01 <samccann> or if it was  all in your stuff so far
16:09:36 <briantist> sort of, yeah, what as added to antisibull generates the needed files to do so. I ended up committing the results of that command to my collection, and now just run the build script it generated
16:09:45 <briantist> (or a slightly modified version of it)
16:10:08 <briantist> so yeah that change absolutely made it possible for the other pieces to fall into place (thanks again felixfontein )
16:10:33 <acozine> yeah, I would definitely like to see that process documented
16:11:04 <acozine> any other open floor items?
16:11:20 <briantist> same! right now the workflow can be read but it's not as good as docs.. https://github.com/ansible-collections/community.hashi_vault/blob/main/.github/workflows/docs.yml
16:11:56 <samccann> #info some details on testing collection docs before merging  - https://github.com/ansible-collections/community.hashi_vault/blob/main/.github/workflows/docs.yml
16:12:06 <acozine> \o/
16:12:32 <acozine> okay, we're at twelve minutes over
16:13:27 <acozine> thanks briantist dericcrago felixfontein gundalow samccann and any lurkers!
16:13:37 <briantist> thanks folks
16:13:52 <acozine> chat welcome in channel any time
16:14:25 <samccann> thanks everyone! great meeting
16:14:54 <acozine> agenda items welcome for next week at https://github.com/ansible/community/issues/579
16:14:56 <briantist> forgot to mention that one of the most important parts of documenting this is going to be describing how to deal with the `pull_request_target` workflow trigger in GHA; it's tricky. But I learned a lot from it. Anyway, it'll end up in docs at some point!
16:15:09 <acozine> heh, it's always something
16:15:12 <acozine> thanks!
16:15:25 <acozine> #endmeeting