16:01:08 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:01:08 <zodbot> Meeting started Tue Feb 14 16:01:08 2023 UTC.
16:01:08 <zodbot> This meeting is logged and archived in a public location.
16:01:08 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:01:08 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:08 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:01:09 <samccann> @room Meeting time! Who is here to talk the docs?
16:01:16 <acozine> o/
16:01:16 <samccann> know you are here. And Welcome to any new folks!
16:01:27 <samccann> #chair acozine
16:01:27 <zodbot> Current chairs: acozine samccann
16:02:01 <oranod> o/
16:02:05 <oranod> hello hello
16:02:54 <acozine> kristianheljas: if you're interested in docs, feel free to join the meeting!
16:02:54 <samccann> #chair Don Naro
16:02:54 <zodbot> Current chairs: Don Naro acozine samccann
16:03:01 <acozine> hey Don
16:03:13 <oranod> hey acozine !
16:03:40 <samccann> Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
16:03:47 <samccann> To any newcomers - again, welcome. We chair all attendees as a way of recognizing your time spent here. And it opens it up for people to add to the meeting minutes with commands like #info or #link (to add a link)
16:03:56 <samccann> General run of the meeting - We go over action items, give docs updates.. maybe have a topic or two, and go over doctooling updates (all the fun stuff behind the scenes that get us docs.ansible.com!)
16:04:13 <kristianheljas> samccann: I am and that was my plan as well, intresting to know what's going on in here!
16:04:29 <samccann> #chair kristianheljas
16:04:29 <zodbot> Current chairs: Don Naro acozine kristianheljas samccann
16:04:38 <samccann> welcome welcome!!!
16:04:49 <samccann> felixfontein: briantist around to talk docs today?
16:06:19 <samccann> official agenda at https://github.com/ansible/community/issues/678#issuecomment-1410919744
16:06:22 <acozine> they may still be recovering from ConfigCamp
16:06:30 * samccann realizes half the time we don't follow the official agenda but anyway...
16:06:46 <samccann> #topic Action Item updates:
16:06:54 <samccann> #info open -Looking for  community maintainer(s) for the sphinx ansible theme
16:07:46 <samccann> a bit on that one ^^ - that's the look and feel of the docsite. It's derrived from the sphinx-rtd-theme and we use it on multiple Ansible project docsites, not just docs.ansible.com.  So if anyone has a desire to get involved in that, we'd welcome the help!
16:08:05 <samccann> #link https://pypi.org/project/sphinx-ansible-theme/
16:08:25 <oranod> #link https://github.com/ansible-community/sphinx_ansible_theme
16:08:50 <oranod> just noticed Felix opened a PR there last week too. yay!
16:09:00 <acozine> nice!
16:09:02 <samccann> woot!
16:09:07 <samccann> yep more the merrier there!
16:09:17 <samccann> #info open samccann to update docs requirements versions before Feb 20
16:09:22 <briantist> felixfontein: sorry I can't make it today :(
16:09:26 <samccann> #link https://github.com/ansible/ansible/pull/79930
16:09:48 <samccann> ok thanks briantist and congrats again on your presentation at the contrib. summit!  some great details there!
16:10:25 <briantist> thanks samccann
16:10:31 <samccann> So on thedocs requirements - just a bit of background - we depend on sphinx, rstcheck and that theme as the big requirements. So once a release, we try to update to the newest packages of those
16:11:03 <felixfontein> o/
16:11:10 <samccann> This time around, we're held back a bit by rstcheck. rstcheck 6 throws some wonky critical messages on our included snippets files, so we're holding it less than 6 this time around
16:11:16 <felixfontein> sorry, I'm a bit afk, but I'll try to listen in :)
16:11:16 <samccann> #chair felixfontein
16:11:16 <zodbot> Current chairs: Don Naro acozine felixfontein kristianheljas samccann
16:11:32 <samccann> welcome welcome! and congrats to you as well on the contributor summit sessions!
16:11:34 <felixfontein> yeah, sticking to rstcheck < 6 is better for now
16:11:40 <felixfontein> thanks!
16:11:49 <felixfontein> without briantist it wouldn't have worked :)
16:11:55 <acozine> is there an issue somewhere that includes the error messages?
16:11:58 <samccann> If folks could take some time today to look at http://docs.testing.ansible.com/ansible/devel/index.html and poke around
16:12:09 <samccann> want to be sure things look good before merging the requirements Pr
16:12:32 <samccann> acozine: https://github.com/ansible/ansible/pull/79930#issuecomment-1421354551
16:12:55 <acozine> samccann: thanks
16:13:09 <samccann> Felix pointed out that the underlying message has been around for years. But in our situation, it's not triggered by code-blocks with no language. seems to be any included snippets that have sphinx directives in them.
16:13:24 <samccann> my plan is to create a test doc to prove that and go over to rstcheck=land and bring it up
16:14:19 <kristianheljas> quite a few major bumps in there, i'll try to poke around there
16:14:22 <felixfontein> :+1: thanks for doing that!
16:14:39 <felixfontein> afk cat is puking somewhere
16:14:47 <samccann> Thanks kristianheljas ! all eyes are helpful
16:15:05 <samccann> I also plan on asking one of the core team folks to look at all the other things that got updated in that PR
16:15:17 <kristianheljas> Maybe make this an action item for folks checking the log later on?
16:15:57 <samccann> #action all  - review the requirements updates in https://github.com/ansible/ansible/pull/79930
16:16:03 <samccann> good idea kristianheljas !
16:17:02 <samccann> the gist of it is - these are the sanity tests that we are updating. so our docs use the same requirements as ansible-test sanity does.  But the scripts that update the sanity test requirements update a bunch of other bits and bobs... so good to have as many eyes on them as possible
16:17:59 <felixfontein> re
16:18:18 <samccann> ro
16:18:22 * samccann wiseguy
16:18:28 <felixfontein> :)
16:18:36 <samccann> #topic Documentation updates
16:18:44 <samccann> #info Ansible 8 roadmap ready to merge
16:18:48 * samccann checks pr
16:19:28 <samccann> ok ci passed to merged!!
16:19:51 <samccann> thanks acozine for writing the roadmap up and thanks everyone for getting the voting done and passed!
16:19:54 <felixfontein> \o/
16:19:57 <felixfontein> thanks everyone :)
16:20:03 <samccann> question tho - how do we make this smoother next time around?
16:20:20 <samccann> we're like 1/2 way through the schedule before getting this one out
16:20:43 <samccann> I 'think' it was because we shortened some timelines.. then hit holidays, and people being out sick etc that stretched this out a bit
16:20:52 <acozine> felixfontein: did you find the cat barf? I hate that "it's somewhere, how long before I step in it?" feeling
16:21:03 <felixfontein> I think this time the winter holidays delayed it for too long
16:21:10 <acozine> agreed
16:21:17 <felixfontein> acozine: I did, and fortunately the cat barfed on stone tiles and not on the wooden floor...
16:21:25 <felixfontein> easier to clean up :)
16:21:35 <acozine> heh, yep
16:21:36 <felixfontein> (and doesn't leave stains...)
16:21:40 <samccann> come for the docs, stay for the cat barf!
16:21:44 <acozine> heh
16:21:45 <felixfontein> :D
16:21:46 <samccann> :-)
16:21:49 <felixfontein> I have some to share, if you want any ;)
16:22:11 <samccann> AAHAH omgosh no. Have enuf w/ dog 'treats' here
16:22:13 <acozine> felixfontein: we have plenty of our own!
16:22:14 <oranod> my cats are always jerks and barf on the carpet
16:22:56 <acozine> mine like the rugs
16:23:26 <acozine> samccann: do we have a public checklist for "docs stuff that always needs updating for a new release"?
16:23:59 <acozine> that might be helpful, and folks could "sign up" for bits ahead of time
16:24:01 <samccann> acozine: not really. We have our docs release checklist, but that's the stuff at the end of the release cycle so to speak
16:24:08 <samccann> but it's a good idea.
16:24:35 <samccann> #action samccann to create a list of 'docs stuff that needs updating for a new release' to catch things like roadmap updates early on
16:24:59 <samccann> I struggle with where to put such a list. It seems odd to put it in the docs themselves. The only other t hing we have is the wiki
16:25:04 <samccann> which even I seldom look at
16:25:40 <samccann> felixfontein: do we have anything like a 'new release checklist' for the package somewhere?
16:25:45 <felixfontein> one reason not to have rugs and carpets... ;)
16:25:50 <samccann> heh
16:26:03 <samccann> even doormats work btw... for  the barfing
16:26:08 <felixfontein> I don't think we have a checklist for that yet
16:26:18 <felixfontein> yeah, barfing on doormats sucks...
16:27:11 <samccann> ok a couple of calls for help...
16:27:19 <samccann> #info looking for help on documenting how to run tests with Ansible pre-releases - https://github.com/ansible-community/community-topics/issues/156
16:27:45 <samccann> and the next one is more a housekeeping set of tasks:
16:27:46 <samccann> #info 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.
16:28:13 * samccann ponders if there's a script someone could write that would open issues on 100+ collections with the same text
16:28:27 <felixfontein> I think c.general and c.sops should be (mostly?) done
16:28:59 <samccann> yeah that issue has a handful that are done. The rest we need to open issues on each collection if we really want folks to do it
16:29:30 <kristianheljas> Are all the listed collection checked?
16:29:32 <samccann> and there's a few other issues like this we could open up - to ask collection owners to do more with those extra-docs.yml files (so we at least get Edit on Github going on most of them etc)
16:30:09 <samccann> kristianheljas: I'm assuming anything unchecked on that issue is a collection that hasn't done it yet. I don't know for sure tho because that would require a lot of digging into each collection.
16:30:41 <samccann> the ask is to just open the issues. If the collection owners close it as done (or never gonna do) that is up to them. But I figure opening the issues gives them the impetus to at least consider it all
16:30:45 <felixfontein> samccann: Edit on Github comes from docs/docsite/links.yml :)
16:30:55 <samccann> oh sorry. knew it was one of them!
16:31:24 <samccann> the issue points to an example of how to open  the collection-level nagogram issue for booleans
16:32:12 <acozine> ah, I said i would do some of those, haven't done any yet
16:32:18 <kristianheljas> Alright, I can help with the issues tomorrow
16:32:20 <acozine> I'll put it back on my list
16:33:01 <samccann> thanks kristianheljas and acozine !! every little bit helps!
16:33:16 <samccann> #info 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/
16:33:28 * samccann realizes I said that before, but haven't done the redirects yet!
16:33:44 <samccann> fwiw it is helping. Google search results aren't reporting 2.5 anymore as top hits!
16:33:54 <samccann> #info examples repo archived as it never got any traction - https://github.com/ansible-community/community-examples/
16:34:47 <samccann> #topic personas and revamping the docsite
16:34:55 <samccann> #info 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
16:35:09 <samccann> got updates from contrib. summit Don Naro ?
16:35:40 <oranod> hey, I think the main update is that folks are probably well aware of the personas at this stage, which is cool.
16:35:56 <oranod> #link https://hackmd.io/pZb5w5JFRQW3RJ73n23tlw?both#/
16:37:10 <oranod> the community topic to vote on the personas has closed. it reached the date but didn't get a lot of votes. imo that's ok because we weren't really making a decision on them, just soliciting acks.
16:37:50 <oranod> totally still open to feedback on personas though so feel free to drop comments here or ping me or add to the hackmd
16:38:04 <samccann> yeah feels like the goal with that vote was to make sure people are aware of what's happening and understand the thoughts behind it etc
16:38:13 <oranod> next step is to fill out the user journeys a bit more and start hacking on the docsite repo to improve that
16:38:40 <oranod> yes, that was the goal. hopefully we've achieved that by now.
16:39:19 <oranod> tbh I'm not too sure how pushed folks are about the personas, if you know what I mean. I think there will be more opinion and debate on the user journey maps and docsite improvements.
16:39:51 <oranod> #link https://github.com/ansible/jinja-docsite
16:40:14 <samccann> yeah for sure people will pipe in on the site design more I think
16:40:21 <acozine> my bet is if you do mockups and maps showing how the pages could move around and what the TOCs could look like, you'll get feedback
16:40:46 <oranod> #info 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
16:41:24 <samccann> Don Naro: how does that jinja site work (or not work) with existing static site generators?
16:41:29 <samccann> or is it instead of a static site generator ?
16:41:55 <oranod> acozine: I think so too. I was hoping to get a bit more activity after the Contrib Summit and the docsite repo but maybe folks need more time to decompress and adjust. I know I'm still not back to 100% myself.
16:43:01 <oranod> samccann: it's a pretty simple static site generator itself. we could use something fancy like Lektor, which looks great. but I wanted to try and do something very simple to start.
16:44:25 <samccann> ok so jinja2-docsite is definitely easier for you to prototype, but we may be open to something else, like lektor, based on community feedback?
16:44:45 <oranod> indeed
16:44:57 <samccann> coolness
16:44:58 <oranod> this belongs to the community
16:45:46 <samccann> #info 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
16:47:01 <samccann> so do we have a call to action here?
16:47:22 <oranod> yes I plan to hit the bullhorn this week for sure
16:47:53 <oranod> should we add the action hashtag here? should probably know that by now but...
16:48:10 <samccann> yeah go for it
16:49:49 <oranod> #action Clone the jinja-docsite repo and show us how you'd like to improve docs.ansible.com https://github.com/ansible/jinja-docsite
16:51:23 <samccann> is there a way to 'see' what that looks like as it's being update?
16:51:26 <samccann> updated that is
16:51:58 <oranod> sure. every merge to the devel branch updates the gh pages at: https://ansible.github.io/jinja-docsite/
16:51:59 <samccann> ah build it locally (reading the contributing.md now)
16:52:05 <samccann> oh nice!
16:52:24 <samccann> #info see https://ansible.github.io/jinja-docsite/ to view how the main branch looks for the proposed new docsite
16:52:29 <samccann> woot!
16:52:39 <samccann> anything else before we open the floor?
16:53:01 <oranod> let's open the dance floor
16:53:09 <samccann> 👯
16:53:14 * acozine does a little twirl
16:53:21 <samccann> #topic Open Floor
16:53:39 <samccann> Now's the time to bring up anything docs related.
16:53:41 <acozine> We can file this one under "before I forget": https://github.com/ansible/ansible/pull/79996
16:53:46 <samccann> have aa burning question? PR or issue you think should be moved on?
16:54:06 <samccann> oo thanks acozine !!
16:54:27 <samccann> merged!
16:54:40 <samccann> anything else on anyone's mind today?
16:55:41 <samccann> ok seems all quiet
16:55:45 <samccann> #endmeeting