15:01:20 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:20 <zodbot> Meeting started Tue Jun 20 15:01:20 2023 UTC.
15:01:20 <zodbot> This meeting is logged and archived in a public location.
15:01:20 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
15:01:20 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:20 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
15:01:29 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:39 <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:01:42 <TVo[m]> Hello o/
15:01:59 <samccann> #chair TVo
15:01:59 <zodbot> Current chairs: TVo samccann
15:02:05 <oranod> o/
15:02:14 <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:02:16 <acozine> o/
15:02:21 <TVo[m]> Just got off the customer/partner experience call.. Was a good one!
15:02:24 <samccann> #chair acozine Don Naro
15:02:24 <zodbot> Current chairs: Don Naro TVo acozine samccann
15:02:31 <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:02:35 <acozine> AFK 5 . . . our fridge is on the fritz
15:02:44 <samccann> Official agenda is https://github.com/ansible/community/issues/678#issuecomment-1589612454
15:04:12 <samccann> Fritz the Fridge is going on Vacation
15:04:13 <samccann> #topic Moving docs out of ansible/ansible
15:04:13 <samccann> This is a repeat from last week but to remind folks
15:04:18 <samccann> #info this is part of putting package docs under ansible steering committee/community control. See https://github.com/ansible-community/community-topics/issues/243
15:04:26 <samccann> #info an interim step is to move all docs out to ansible/ansible-documentation. From there, we can iterate faster to get to the point where the community package docs are under community control (likely another repo in ansible-community org) and separate from core docs.
15:04:41 <samccann> So we are starting our first week of trying to live in the new repo (for devel docs only so far).
15:05:23 <samccann> #info new docs repo is https://github.com/ansible/ansible-documentation
15:05:53 <samccann> as PRs come into ansible/ansible for docs, I'm requesting they move to the new repo
15:06:49 <sutapa_bhattacha> o/
15:07:02 <oranod> hi sutapa_bhattacharjee 👋
15:08:13 <oranod> samccann: has there been any update on how long until the split will be official and `docs/docsite` is removed from `ansible/ansible`?
15:08:15 <samccann> ...and I have a project board I created on Friday to show the moves etc, but somehow can't figure out how to make it public, but anyway. 9 PR moves so far
15:08:23 <samccann> #chair sutapa_bhattacharjee
15:08:23 <zodbot> Current chairs: Don Naro TVo acozine samccann sutapa_bhattacharjee
15:08:44 <acozine> I'm torn about moving docs out of ansible/ansible. I see the appeal of putting package docs under community control. I also worry that moving docs away from the code makes them a backwater.
15:08:52 <samccann> Don Naro: we are in a two-week trial period that only started last Thursday. so... two weeks from then :-)
15:08:56 <oranod> and will we also move all the docs only issues and other things like the easyfix?
15:09:07 <acozine> The advantage of having documentation live with the code is that it's easier  for folks who update the code to also update the documentation.
15:09:22 <oranod> s/update/change. so no change. I wonder if two weeks is long enough?
15:09:31 <samccann> Don Naro: yes, once the trial/review period is over, all docs issues will likely move
15:09:46 <acozine> Once docs live somewhere else, it's easy to forget that a change to the code must also be reflected in the documentation
15:10:44 <samccann> acozine: yeah that's the big risk. On paper, the core team is committed to keeping the docs valid in the new repo, and I do  think they will. It's harder to say about community people adding code to ansible/ansible tho
15:11:06 <oranod> acozine: I share that concern. for the core team I would like to establish and agree on a process for documenting features and retaining technical stewardship. for the community folks, esp arbitrary contributors, I think there is more of a risk.
15:11:17 <acozine> is this move still under consideration? or is it a "done deal"?
15:11:23 <felixfontein> o/
15:11:30 <felixfontein> sorry, had a meeting that took too long
15:11:33 <oranod> hey felixfontein
15:11:43 <samccann> #chair felixfontein
15:11:43 <zodbot> Current chairs: Don Naro TVo acozine felixfontein samccann sutapa_bhattacharjee
15:13:01 <samccann> my thoughts are this trial period of two weeks is to see if anything major shows up as a problem
15:13:43 <oranod> it will mean if you add a bit of code to ansible/ansible then you'll need a separate PR for the corresponding docs. and I also worry that we might lose some of the "good samaritans" who fix docs when they notice something missing or a needed change while doing other work.
15:13:46 <samccann> I personally feel the 'major' would be code being added to ansible/ansible with no docs coverage and yeah, two weeks isn't long enough to determine that. But we can't live  in limbo for much longer than that
15:14:34 <acozine> Ansible has been successful in large part because our documentation has been correct and complete (though often badly organized).
15:14:35 <samccann> Don Naro: yeah not sure how we'd track whether we are lacking good samaritan PRs so to speak
15:15:09 <samccann> after doing weekly backports for a year, I can say we normally get a handful of PRs a week. Sometimes it's more, sometimes it's less
15:15:36 <samccann> And in this 'limbo' state, we can't tell because edit on github is still going to ansible/ansible
15:15:46 <samccann> from /latest/ docs
15:16:31 <acozine> I'm not so worried about losing "edit on GitHub" contribuitons, those folks are reading the docs when they see a typo or whatever
15:16:34 <samccann> #info Folks are expressing concerns that we will lose technical contributors to docs in the new repo over time, and the long-term health of the documentation will be impacted by this move
15:16:40 <felixfontein> will the docs for the next release be built from the new repo?
15:16:51 <acozine> it's more the folks who are making code changes and update the docs while they're doing that
15:16:58 <oranod> docs are building from the new repo today
15:17:02 <samccann> felixfontein: after the two week trial, all active docs will be from the new repo, yes
15:17:08 <felixfontein> \o/
15:17:27 <felixfontein> does that also mean that we can now update antsibull-docs whenever we want, and also to new major/minor versions for the stable branches?
15:17:45 <samccann> so Ansible 8 (aka latest) and devel. And core-2.15. I'm less sure about core-2.13 and 2.14 as the only time we touch  those in docs land is to update version switcher (aka every 6 months)
15:18:01 <acozine> it sounds like this is less a "trial period" and more a "QA period" - is there any chance the docs will stay / move back to ansible/ansible?
15:18:12 <samccann> felixfontein: I believe once the move is permanent, then yes, we control antsibull-docs updates
15:18:45 <oranod> felixfontein: yes. part of the move is motivated by adopting a new release cadence and not using the same as core
15:19:58 <oranod> acozine: yeah it is more of a QA period. I think if the split does go ahead then it would be unlikely for them to move back.
15:20:31 <oranod> Sandra could know more there but that's just my feelign
15:21:11 <acozine> Don Naro: "if" the split goes ahead? What are the chances it will not go ahead?
15:21:12 <oranod> s/feelign/feeling/
15:21:33 <felixfontein> samccann: oranod: I was hoping so, I really like that :)
15:22:05 <oranod> I don't want to try and say what the chances are but I think if we uncover serious concerns or broken stuff then we could go back and put the brakes on
15:22:42 <oranod> I feel like part of the point is to kind of handover all the docs development to community and treat it like a separate project
15:23:08 <samccann> yeah my feeling is the same. There's strong momentum behind the move so it would be  something truly significant to stop it. I don't think our collective fears that docs might go stale is enough to stop it
15:23:11 <oranod> but I def share the concern that we shouldn't kneecap our community contributors so to speak
15:24:09 <oranod> sorry if that's not the right way to express it but I do see the risk for those good samaritans I referred to earlier
15:24:57 <oranod> felixfontein: there's also a full working copy of the `hacking` dir in `ansible-documentation` that we can get our hands on
15:25:56 <oranod> it would be nice to have more strategy around ensuring we don't lose the good samaritans and that we develop some consistent messaging to help contributors adapt to the changes
15:27:12 <acozine> Thanks for being honest - if I had the deciding vote, I would probably vote against moving the docs, because from my perspective the risks outweigh the rewards. However, since it has already been decided, I will try to focus more on the rewards.
15:27:31 <acozine> And there are some good rewards.
15:28:30 <oranod> ultimately I think it will be something that really strengthens the community but I too worry about how this will impact the contributors
15:29:38 <samccann> #info identified risk - we lose technical contributors.  identified benefits - faster iteration on antsibull-docs updates, ability to split the core from community docs, and lead toward full community control over the documentation
15:30:25 <acozine> we don't just lose contributors, we potentially lose docs updates across the board; it's just too easy to forget or overlook docs updates when they're "somewhere else"
15:30:59 <acozine> it's an extra PR, and it's much harder to enforce the "this also needs a docs change" rule
15:31:00 <samccann> #undo
15:31:00 <zodbot> Removing item from minutes: INFO by samccann at 15:29:38 : identified risk - we lose technical contributors.  identified benefits - faster iteration on antsibull-docs updates, ability to split the core from community docs, and lead toward full community control over the documentation
15:31:56 <acozine> unless the docs team is policing the core repo, attending core standups, etc., etc.
15:32:07 <samccann> #info identified risk - the docs lose technical accuracy over  time because it's an extra step to remember to open a docs PR in another repo. Identified benefits - aster iteration on antsibull-docs updates, ability to split the core from community docs, and lead toward full community control over the documentation
15:32:15 <samccann> yeah there is no docs team
15:32:21 <samccann> just to state that clearly ;-)
15:32:52 <oranod> well, there is the core team. I feel like they should see themselves as part of the docs team.
15:32:57 <samccann> but it's possible to track ansible/ansible PRs that are marked 'feature' and see if a matching docs PR ever shows up.
15:33:06 <oranod> maybe they already do 😉
15:33:07 <felixfontein> another possibility would be to move *some* parts of the docs and docs process out of ansible/ansible, while keeping others - that would solve *some* of the above problems, but also introduce new ones
15:33:27 <acozine> yeah, that makes building the docs a lot harder
15:33:49 <acozine> I'm sorry, I don't mean to derail everyone, especially if there's nothing we can do to change the current trajectory.
15:33:50 <oranod> that's kind of what I was hoping to achieve. keeping a subset of docs in ansible/ansible.
15:34:21 <felixfontein> which docs will stay in ansible/ansible (next to the docs that are part of the code directory, i.e. lib/ansible/)?
15:34:22 <samccann> I think core would prefer even their subset of docs to be in another repo.
15:34:50 <samccann> At the moment, no docs stay except those that are generated (aka cli command pages etc)
15:35:34 <samccann> fwiw there is already a PR available (not merged) that will delete the /docs folder from ansible/ansible
15:36:53 <samccann> one thing I expected to hear from are the package folks. I thought some of the distros repackage ansible w the docs
15:37:09 <samccann> but I didn't get any feedback from the package channel here so maybe I'm delusional?
15:37:53 <gwmngilfen-work> acozine: Please don't apologise for keeping us honest. And we probably could change some of the detail, if we need to - so please do keep telling us things we should hear.
15:38:21 <gwmngilfen-work> Momentum is hard to shift though :)
15:38:49 <oranod> I spoke with anwesha about it and I think where the package stuff touches docs is all manual PRs so the split shouldn't break anything there
15:39:30 <samccann> I'm not talking about our ansible package, I'm talking about folks like Fedora etc. I thought someone somewhere also rebuilt docs from source
15:39:48 <samccann> felixfontein: does that sound at all familiar? ^^
15:40:50 <samccann> ok we do have another important  topic so should we shift to that?
15:41:14 <samccann> #topic Getting Started guide revamp
15:41:21 <samccann> We have a couple of PRs to add content to the getting started guide:
15:41:23 <felixfontein> samccann: sounds correct to me
15:41:43 <samccann> thanks I'll ping you later on that topic and see if there are specific people we should reach out to
15:41:44 <samccann> #link https://github.com/ansible/ansible-documentation/pull/14
15:41:53 <samccann> This one moves the 'what is ansible' into the getting started guide, based on reader feedback.
15:42:21 <samccann> It also introduces a formal folder structure that is compatible with other ecosystem projects, installs vscode and lint and commits it all to github. This is all before creating the first playbook.
15:42:31 <samccann> and another one:
15:42:38 <samccann> #link https://github.com/ansible-community/community-team/issues/243#issuecomment-1588912447
15:42:48 <samccann> This one discusses where to put an overview of execution environments and a quickstart for that.
15:42:54 <samccann> Note it uses builder and navigator in the quickstart, so can't really live with the builder docs.
15:43:00 <samccann> #info EE content that is being discussed is here - https://github.com/ansible/community-docs/tree/main/execution_environments
15:43:28 <samccann> Sorry for the huge info dump but we have two good examples of content to consider and how it impacts the existing getting started guide
15:43:39 <samccann> https://docs.ansible.com/ansible/latest/getting_started/index.html
15:44:04 <oranod> I think the first one has gone a little away from the meaning of the issue that I created tbh
15:44:49 <samccann> so the first one - the reader feedback that started it was that a reddit person seeing the new getting started guide said it just jumped right in w/o saying what is ansible and why should I care
15:45:16 <samccann> and then a separate issue to make the folder structure match what is compatible with things like AWX and maybe navigator?
15:45:16 <oranod> the point there is basically to do some things that will make your life easier "down the line" and establish a pattern for keeping all your playbooks and other bits under a single directory structure instead of scattered across a number of folders
15:45:46 <oranod> agreed that maybe that PR is combining two things that should be in separate PRs
15:46:11 <samccann> yeah I like the idea of introducing the folder structure etc, but I think it should be AFTER the existing getting started content. A sort of 'what's next' section to future-proof your efforts
15:46:26 <oranod> I've been talking to jklech about it
15:47:13 <oranod> well, the existing getting started refers to the etc/hosts file and stuff like that so it needs to be rewritten or it'll contradict itself if it comes afterwards
15:47:36 <oranod> know what I mean? that one honestly isn't a really big change.
15:47:38 <samccann> It should still focus FIRST on the hello-world
15:48:01 <oranod> yeah the stuff about lint and all that has got mixed up in there
15:48:04 <samccann> but yeah if it needs a change here and there ,cool, but not the entire folder structure introduced before the hello world example
15:49:33 <acozine> yeah, I think a getting started should give readers a quick win before going into the long-term stuff
15:50:00 <oranod> I totally agree with that
15:50:14 <acozine> start with "here's how you Ansible" and then "Now that you see how easy it is, you probably want to automate a lot of stuff, here are some ideas to make it easy to track all your automation projects"
15:50:52 <acozine> because one playbook becomes a dozen very quickly
15:51:43 <samccann> #agreed - getting started should give a quick win before introducing long-term stuff. Move the folder structure content to a page at the end of the existing getting started for example
15:51:50 <samccann> Ok moving on to EEs
15:52:02 <oranod> no, I think that is a misinterpretation
15:52:08 <samccann> #undo
15:52:08 <zodbot> Removing item from minutes: AGREED by samccann at 15:51:43 : - getting started should give a quick win before introducing long-term stuff. Move the folder structure content to a page at the end of the existing getting started for example
15:52:14 <samccann> ok give it a summary don
15:52:18 <oranod> the folder structure content doesn't belong at the end
15:52:29 <oranod> my summary was earlier
15:53:05 <oranod> oh, sorry. do you mean with the hashtag for the minutes?
15:53:30 <samccann> you disagreed with my summary so yes, please summarize first. then wwhen we agree, we add to minutes
15:53:53 <samccann> keeping in mind we still need to cover EEs
15:54:27 <oranod> summary is that we make some simple changes to the getting started to encourage the "best practice" of having a single directory structure
15:54:54 <oranod> there shouldn't be any separate folder structure content
15:55:12 <samccann> ok not sure I agree then
15:55:23 <oranod> I just think that PR might have got a little mixed up in a few places and I'm working with jklech on it
15:55:38 <samccann> I do understand wanting to get the folder structure correct, I disagree that it belongs sprinkled within the hello world example
15:55:44 <samccann> start simple, build up
15:56:15 <oranod> let me just keep working with jklech on it and it'll get there
15:56:15 <acozine> that PR is a pretty big changeset, it might be easier to discuss as 2 or 3 PRs
15:56:17 <samccann> so yes, their hello world will be in the wrong folder. But it's a toy playbook. After that we say 'here is the recommended structure that works with other ansible projects'
15:57:31 <acozine> we could even walk through the change - something like "we didn't tell you where to put your first playbook, but before you write your second playbook, it's a good idea to set up a directory structure that will keep your automation organized for the long term."
15:58:21 <acozine> then show mkdir /path/to/playbooks_dir and mv ./my_first_playbook.yml /path/to/playbooks_dir/
15:58:54 <samccann> ok maybe then the next step is to ask the PR owner to split the PR - one PR moves the 'what is ansible' into the getting started
15:59:15 <samccann> 2nd PR does...the folder structure "somehow" and we can see that clearly to review
15:59:35 <samccann> We have one minute left but we do have EEs to talk about as well. Is anyone able to hang around another 15 min or so?
15:59:55 <oranod> I can hang around
16:00:11 <oranod> but that's another I think we should wait until we have something solid to review
16:00:22 <acozine> sorry, I have to head to my next meeting; it's one I run, so it's hard to skip ;)
16:00:34 * acozine waves
16:00:40 <samccann> heh ok thanks!
16:00:43 <samccann> https://github.com/ansible/community-docs/tree/main/execution_environments
16:01:17 <samccann> that's the content so far for EEs that we're discussing now. It gives an overview, and then a quick start walkthrough... kind of like the 'hellow world' but for execution environments.
16:01:50 <samccann> it touches a couple of projects (builder and navigator) so isn't appropriate to live in the builder docs. It would also be kind of 'hidden' there. So the proposal is to add it to the Ansible docs
16:02:01 <samccann> I think there were two ideas -
16:02:07 <samccann> 1 - add it to the user guide somewhere
16:02:16 <samccann> 2 - add it to the getting started guide
16:02:24 <samccann> is that about right Don Naro ?
16:03:38 <oranod> I think 1 was more like adding it to a "How To" section of the docs that does not yet exist. however it's not a "How To"
16:04:09 <oranod> and 2 is really about extending the existing getting started and building on the hello world
16:04:11 <samccann> yeah I think you me and andersson007_ did finally agree it's more of a quick start/getting started for EEs?
16:05:29 <samccann> My nickel is that it's not a logical extention of the existing getting started. I don't see someone brand new to Ansible going from their first playbook to creating an execution environment
16:05:51 <samccann> I can see it in the same area, but being specifically 'Getting started with EEs' so to speak
16:06:26 <samccann> I feel like EEs are an intermediate/advance ansible user person.
16:07:30 <oranod> it builds on the concept of inventories and gets into containers with ansible. containers are pretty much standard these days so it seems foundational to me.
16:07:57 <oranod> that tutorial also shows how to use a collection pretty well too
16:08:43 <oranod> I don't mean a logical extension of getting started actually, more that it's something that resides in the same section of the docs and builds on the hello world
16:08:58 <samccann> ok sounds like we are in agreement
16:09:20 <samccann> The EE content (overview and getting started) should be its own guide in the Getting started navigation area on docs.asible.com
16:09:24 <samccann> does that sound right?
16:09:46 <oranod> yeah, I think all of this will make a lot more sense in a week or two when we get jklech 's getting started PR all nice and neat then add in andersson007_ 's ee PR
16:10:01 <oranod> that sounds right to me
16:10:17 <samccann> I don't see the EE PR being dependent on anything else if it's a separate getting started with EE guide
16:10:36 <oranod> it's not dependent but the two will fit together nicely
16:10:56 <samccann> so Andrei can move is content today so to speak and we can merge afte review, right?
16:11:08 * samccann uploaded an image: (7KiB) < https://libera.ems.host/_matrix/media/v3/download/ansible.im/89e62ea3fa34655f2525c568a219d17c4994f141/image.png >
16:11:11 <samccann> and it goes below ^^
16:12:18 <oranod> | Ansible Getting Started
16:12:18 <oranod> |-- Getting started with Ansible
16:12:18 <oranod> |-- Getting started with execution environments (or whatever title works best)
16:12:22 <oranod> like that?
16:12:25 <samccann> yeah
16:12:27 <oranod> yeah
16:12:36 <samccann> #agreed The EE content (overview and getting started) should be its own guide in the Getting started navigation area on docs.asible.com
16:12:48 <samccann> ok cool. In case anyone else is around
16:12:52 <samccann> #topic Open Floor
16:13:09 <samccann> anhyone have anything else to bring up? and thanks for hanging around extra for this today!
16:13:28 <oranod> nothing from me, thanks
16:13:53 <samccann> #endmeeting