15:02:01 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:02:01 <zodbot> Meeting started Tue Jun  6 15:02:01 2023 UTC.
15:02:01 <zodbot> This meeting is logged and archived in a public location.
15:02:01 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:02:01 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:02:01 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:02:02 <acozine> o/
15:02:12 <oranod> o/
15:02:14 <samccann> @room Meeting time! Who is here to talk the docs?
15:02:33 <acozine> a bunch of us got here early ;)
15:02:34 <samccann> #chair acozine sutapa_bhattacharjee Don Naro TVo
15:02:34 <zodbot> Current chairs: Don Naro TVo acozine samccann sutapa_bhattacharjee
15:02:49 <samccann> yes! exciting to see folks here!
15:02:59 <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!
15:03:10 <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)
15:03:43 <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!)
15:03:50 <samccann> #info official agenda at https://github.com/ansible/community/issues/678#issuecomment-1568714048
15:04:05 <samccann> #topic Action Items
15:04:20 <samccann> #info closed samccann to inform community-writers about EE epic for a place to help out editorially and with info architecture etc
15:04:36 <samccann> #info closed issue in community-topic for requesting cheatsheet help and on reddit as well - https://github.com/ansible-community/community-topics/issues/232
15:04:54 <samccann> #topic Documentation Updates
15:05:24 <samccann> #info so far minor feedback on cheatsheet ideas but just put the community-topic on this week's agenda so might get more attention after tomorrow's meeting
15:05:32 <samccann> community WG meeting that is
15:06:16 <samccann> I have an interesting pandoras box to open up, but want to see if other folks have docs updates etc before I crack that one open
15:06:26 <acozine> heh
15:07:30 <samccann> #info a lot of attention happening on builder docs - https://github.com/ansible/ansible-builder/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
15:07:46 <samccann> so pr reviews welcome for sure over there
15:09:13 <samccann> sutapa_bhattacharjee: - I'm way behind on awx operator docs. I think you fixed the CI problem but I lost track on whether Don Naro or someone else had an idea before we beg for a merge?
15:09:44 <samccann> #info awx operator mkdocs PR - https://github.com/ansible/awx-operator/pull/1363
15:09:49 <sutapa_bhattacha> I think we are missing the molecule test fix
15:10:04 <sutapa_bhattacha> for which Don pinged
15:10:34 <samccann> oh and I've waited so long the PR needs to be rebased. did you notice that? and do you need help with understanding a git rebase?
15:10:56 <sutapa_bhattacha> I will manage that, hopefully :)
15:11:16 <sutapa_bhattacha> If not, you can expect a ping later
15:11:32 <samccann> :-) sounds good
15:11:59 <samccann> anyone have anything else on docs updates?
15:12:46 <oranod> #info I opened this issue to improve / rewrite getting started if anyone is interested: https://github.com/ansible/ansible/issues/80941
15:12:54 <acozine> I'm looking at open PRs on ansible/ansible, looks like there are a few that would be easy to merge. Does that fall under "docs updates"?
15:13:49 <samccann> acozine: yeah I'm waaay behind on my backlog. But if you or others can go in and review/comment/approve/ that will help me move them along later  this week
15:14:19 <acozine> Sounds good!
15:15:06 <samccann> #topic Moving (some) community docs out of ansible/ansible
15:15:15 * samccann creaaaks open that pandoras box
15:15:31 <samccann> So this idea has cropped up multiple times in the past and I just noticed..
15:15:48 <samccann> #info moving community docs out of ansible/ansible- https://github.com/ansible-community/community-topics/issues/240
15:16:25 <samccann> someone created a topic for it ^^
15:16:25 <samccann> So I'll reiterate some background details
15:16:54 <samccann> First off - in my limited skillset, I could only publish docs if they lived in ansible/ansible repo. That means the list of docs/rst files there has grown.  Some of those aren't related directly to ansible-core
15:17:24 <samccann> Such as all the collection requirements etc docs for contributors/collection maintainers etc. That I think is the gist of that community-topic
15:17:45 <samccann> There are other files that don't really relate to a particular core/Ansible release - like how to join the community etc
15:17:56 <acozine> Are all of the community docs "versionless"?
15:18:30 <samccann> I think all the collection contributor docs are versionless, and how to join the community is versionless, yes
15:18:35 <acozine> or do we need to create a version-switcher for community docs?
15:18:37 <samccann> at one point I thought dev guides were versionless but someone corrected me on that one
15:19:42 <samccann> Don Naro might recall other categories of docs that could potentially be moved out of ansible/ansible repo as well. I'm probably forgetting some
15:20:11 <samccann> But there is another point we talked about in the past as well. Regardless of where the source files live, where should the guides be published?
15:20:39 <samccann> Back when we originally did the collection split out of ansible/ansible, there were very strong desires to keep all the guides still at docs.ansible.com/ansible
15:21:02 <samccann> so for example, a user woudl still notice an entire community/contributing section in the left-hand navigation etc
15:21:51 <samccann> Part of that was - make it obvious so people can grow/change in their ansible journeys.  Another part? our site search is ..meh at best. So anything removed from that url would no longer be searchable with the current publishing setup.
15:22:23 <samccann> So...that's the background and how all the different things interrelate etc.  Open for discussion now.. what are the thoughts here on any/all of this?
15:24:22 <acozine> I'm in favor of moving the documentation about the community onto a platform where the community can update it
15:24:48 <acozine> but as your overview shows, the details get tricky
15:24:54 <oranod> personally I feel like docs.ansible.com belongs to the community and we should be careful with it because it has built up all that SEO authority
15:26:08 <acozine> if we can find a solution where those docs can be published from their new home to docs.ansible.com/ansible, that would be ideal
15:26:27 <acozine> hrm, I should have followed Don Naro's trick and made that `code`
15:26:53 <oranod> I've actually been working on that and hope to have something to share real soon now
15:27:03 <samccann> acozine: so the source could move but the published URL must stay the same is what you are saying?
15:27:48 <acozine> must? I don't know - I'm hoping we can move the source and still publish it to the same URL
15:27:56 <oranod> we can
15:28:01 <acozine> awesome!
15:28:47 <acozine> I don't know which way I'd go if it were truly either/or, but if we have a third option, that would make me very happy!
15:32:06 <samccann> #info moving source files makes sense to make updates easier by community. Ideally they publish to the same urls they live at today to keep SEO in place and reader familiarity
15:32:20 <samccann> Would also ask y'all to post on that community-topic as well.
15:33:52 <samccann> ok not as big of a pandoras box than I thought it might be :-)
15:34:15 <samccann> #topic doctools and docsite updates
15:34:24 <samccann> Anything in this category to talk about today?
15:35:10 <oranod> not a whole lot from me. I opened a bunch of issues for the jinja templates for the docsite and they're in the backlog column here: https://github.com/orgs/ansible-community/projects/3/views/6
15:36:06 <oranod> also I got the jinja template for controller docs updated so now it should be a lot easier to add translations and archives (no need to directly edit HTML)
15:36:51 <samccann> Is there a 'how to update the docsite' instructions somewhere? I can't tell if these are things anyone could go in and fix, or if they require jinja2 knowledge or html knowledge?
15:37:05 <TVo[m]> thanks Don Naro - how does one update them now?
15:38:35 <oranod> yeah I guess I should update the readme there. sorry. so basically you just add new entries to the yaml files. for example, if you wanted to add a version to the controller archive, you'd edit: https://github.com/ansible/jinja-docsite/blob/main/data/controller_archive.yaml
15:39:24 <oranod> for instance if you wanted to archive 4.2.3 to the archive, you'd just update that file with this:... (full message at <https://libera.ems.host/_matrix/media/v3/download/libera.chat/3faca667080b5070a4b44cd621d38e34dc0a6106>)
15:39:56 <TVo[m]> Easy enough. Cool!
15:40:02 <oranod> I'll get on the readme
15:40:44 <acozine> heh, it's like the shoemaker's family going barefoot
15:40:52 <oranod> probably also need to move away from that jinja-docsite and put everything in the docsite repo
15:40:52 <acozine> the docs team behind on its own docs
15:41:22 <acozine> there are always so many priorities, we don't always make ourselves the top one
15:41:32 <samccann> heh
15:42:13 <oranod> samccann: at some point we should probably discuss removing the oldsite toggle. I'd like to do that before we move the source over to the `docsite` repo.
15:42:43 <samccann> ok. I'll dig out the current stats just to be sure there aren't a flood of people going to the old site suddenly
15:44:50 <oranod> sounds good, thx. I've got my fingers crossed we can drop that soon enough.
15:46:19 <samccann> #topic Open Floor
15:46:35 <samccann> Anything else docs-related anyone wants to bring up?
15:46:40 <TVo[m]> I don't know if this is appropriate for community discussion, but I'd like to open the product-docs repo up to the public and allow community contribution. I know that Don has been helping me move towards this goal, but I don't know exactly when it'll occur.
15:47:03 <samccann> woot! yeah valid topic for sure!
15:48:28 <acozine> awesome!
15:49:01 <oranod> TVo: what if we move community content to `awx/docs` and keep `product-docs` as-is and make it more legacy?
15:50:27 <acozine> would both repos publish to the same main URL?
15:50:59 <TVo[m]> There are already docs on awx/docs that developers use. I would have to further discuss with them the appropriate next steps.
15:51:14 <acozine> I need to run - biobreak before my next meeting
15:51:25 <acozine> thanks everybody!
15:51:41 <TVo[m]> the awx/docs don't get published, they're just "there", so that would need to be completely redone.
15:51:47 <TVo[m]> bye acozine
15:51:50 <samccann> thanks acozine !
15:51:52 * acozine waves
15:52:15 <samccann> I'll just toss out there that I think RH would have problems if we turn product-docs into awx docs
15:52:29 <oranod> yeah, I think we need to drag the AWX team into it. but we could have the two things side by side because current AWX docs (the unpublished developer content) is MD while your controller docs are RST
15:53:04 <oranod> we wouldn't turn all of product docs into awx docs
15:53:18 <samccann> for those following along, the product-doc is a currently internal only github repository for the ansible-controller docs.  Ansible-controller is the red hat (enterprise/customer) version of AWX (the upstream project)
15:53:55 <oranod> that's why I think it makes sense to keep product-docs as-is, so we can keep downstream and community more isolated
15:54:19 <oranod> and we can build awx/docs on readthedocs like the rest of the ecosystem
15:54:37 <TVo[m]> Then I'd have two places to update content?
15:55:42 <oranod> well, I'd hope that the product-docs repo would become kind of a legacy thing and only updated for critical issues
15:56:24 <samccann> let me try to rephrase to see if I understand
15:56:50 <samccann> 1 - copy some level of product-docs to awx/docs so we get better upstream awx docs (in combination with what is already there)
15:57:14 <samccann> 1 - de-emphasize Tvo's work on product-docs and have her focus on the now-revamped awx docs?
15:57:22 <samccann> sorry  that should have been #2 lol
15:57:38 <samccann> and 'mystery person' takes over controller docs somewhere else?
15:57:53 <samccann> (which should be #3... must learn not to start a count if I can't keep it going!)
15:58:13 <TVo[m]> How did you make the text red?
15:58:40 <TVo[m]> Yea I don't like #3 at all, or #2 for that matter.
15:59:25 <oranod> yeah let's not try to hash it all out here right now. it's great to see this though TVo
15:59:39 <oranod> it's tricky because downstream is involved
15:59:51 <oranod> more community docs is certainly a good thing
15:59:56 <TVo[m]> Yea I figured just throwing it out there, no need to deep dive into this here.
16:00:30 <samccann> ok cool were close to the top of the hour but before we drop this entirely - is the next step still to see how we can open up the existing product-doc repo to community PRs etc?
16:01:58 <TVo[m]> yes
16:02:33 <samccann> ok cool
16:02:40 <samccann> we'll call this a wrap!
16:02:43 <samccann> #endmeeting