15:01:20 #startmeeting Documentation Working Group aka DaWGs 15:01:20 Meeting started Tue Jun 20 15:01:20 2023 UTC. 15:01:20 This meeting is logged and archived in a public location. 15:01:20 The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions. 15:01:20 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:01:20 The meeting name has been set to 'documentation_working_group_aka_dawgs' 15:01:29 @room Meeting time! Who is here to talk the docs? 15:01:39 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 Hello o/ 15:01:59 #chair TVo 15:01:59 Current chairs: TVo samccann 15:02:05 o/ 15:02:14 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 o/ 15:02:21 Just got off the customer/partner experience call.. Was a good one! 15:02:24 #chair acozine Don Naro 15:02:24 Current chairs: Don Naro TVo acozine samccann 15:02:31 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 AFK 5 . . . our fridge is on the fritz 15:02:44 Official agenda is https://github.com/ansible/community/issues/678#issuecomment-1589612454 15:04:12 Fritz the Fridge is going on Vacation 15:04:13 #topic Moving docs out of ansible/ansible 15:04:13 This is a repeat from last week but to remind folks 15:04:18 #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 #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 So we are starting our first week of trying to live in the new repo (for devel docs only so far). 15:05:23 #info new docs repo is https://github.com/ansible/ansible-documentation 15:05:53 as PRs come into ansible/ansible for docs, I'm requesting they move to the new repo 15:06:49 o/ 15:07:02 hi sutapa_bhattacharjee 👋 15:08:13 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 ...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 #chair sutapa_bhattacharjee 15:08:23 Current chairs: Don Naro TVo acozine samccann sutapa_bhattacharjee 15:08:44 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 Don Naro: we are in a two-week trial period that only started last Thursday. so... two weeks from then :-) 15:08:56 and will we also move all the docs only issues and other things like the easyfix? 15:09:07 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 s/update/change. so no change. I wonder if two weeks is long enough? 15:09:31 Don Naro: yes, once the trial/review period is over, all docs issues will likely move 15:09:46 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 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 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 is this move still under consideration? or is it a "done deal"? 15:11:23 o/ 15:11:30 sorry, had a meeting that took too long 15:11:33 hey felixfontein 15:11:43 #chair felixfontein 15:11:43 Current chairs: Don Naro TVo acozine felixfontein samccann sutapa_bhattacharjee 15:13:01 my thoughts are this trial period of two weeks is to see if anything major shows up as a problem 15:13:43 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 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 Ansible has been successful in large part because our documentation has been correct and complete (though often badly organized). 15:14:35 Don Naro: yeah not sure how we'd track whether we are lacking good samaritan PRs so to speak 15:15:09 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 And in this 'limbo' state, we can't tell because edit on github is still going to ansible/ansible 15:15:46 from /latest/ docs 15:16:31 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 #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 will the docs for the next release be built from the new repo? 15:16:51 it's more the folks who are making code changes and update the docs while they're doing that 15:16:58 docs are building from the new repo today 15:17:02 felixfontein: after the two week trial, all active docs will be from the new repo, yes 15:17:08 \o/ 15:17:27 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 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 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 felixfontein: I believe once the move is permanent, then yes, we control antsibull-docs updates 15:18:45 felixfontein: yes. part of the move is motivated by adopting a new release cadence and not using the same as core 15:19:58 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 Sandra could know more there but that's just my feelign 15:21:11 Don Naro: "if" the split goes ahead? What are the chances it will not go ahead? 15:21:12 s/feelign/feeling/ 15:21:33 samccann: oranod: I was hoping so, I really like that :) 15:22:05 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 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 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 but I def share the concern that we shouldn't kneecap our community contributors so to speak 15:24:09 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 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 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 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 And there are some good rewards. 15:28:30 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 #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 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 it's an extra PR, and it's much harder to enforce the "this also needs a docs change" rule 15:31:00 #undo 15:31:00 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 unless the docs team is policing the core repo, attending core standups, etc., etc. 15:32:07 #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 yeah there is no docs team 15:32:21 just to state that clearly ;-) 15:32:52 well, there is the core team. I feel like they should see themselves as part of the docs team. 15:32:57 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 maybe they already do 😉 15:33:07 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 yeah, that makes building the docs a lot harder 15:33:49 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 that's kind of what I was hoping to achieve. keeping a subset of docs in ansible/ansible. 15:34:21 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 I think core would prefer even their subset of docs to be in another repo. 15:34:50 At the moment, no docs stay except those that are generated (aka cli command pages etc) 15:35:34 fwiw there is already a PR available (not merged) that will delete the /docs folder from ansible/ansible 15:36:53 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 but I didn't get any feedback from the package channel here so maybe I'm delusional? 15:37:53 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 Momentum is hard to shift though :) 15:38:49 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 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 felixfontein: does that sound at all familiar? ^^ 15:40:50 ok we do have another important topic so should we shift to that? 15:41:14 #topic Getting Started guide revamp 15:41:21 We have a couple of PRs to add content to the getting started guide: 15:41:23 samccann: sounds correct to me 15:41:43 thanks I'll ping you later on that topic and see if there are specific people we should reach out to 15:41:44 #link https://github.com/ansible/ansible-documentation/pull/14 15:41:53 This one moves the 'what is ansible' into the getting started guide, based on reader feedback. 15:42:21 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 and another one: 15:42:38 #link https://github.com/ansible-community/community-team/issues/243#issuecomment-1588912447 15:42:48 This one discusses where to put an overview of execution environments and a quickstart for that. 15:42:54 Note it uses builder and navigator in the quickstart, so can't really live with the builder docs. 15:43:00 #info EE content that is being discussed is here - https://github.com/ansible/community-docs/tree/main/execution_environments 15:43:28 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 https://docs.ansible.com/ansible/latest/getting_started/index.html 15:44:04 I think the first one has gone a little away from the meaning of the issue that I created tbh 15:44:49 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 and then a separate issue to make the folder structure match what is compatible with things like AWX and maybe navigator? 15:45:16 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 agreed that maybe that PR is combining two things that should be in separate PRs 15:46:11 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 I've been talking to jklech about it 15:47:13 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 know what I mean? that one honestly isn't a really big change. 15:47:38 It should still focus FIRST on the hello-world 15:48:01 yeah the stuff about lint and all that has got mixed up in there 15:48:04 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 yeah, I think a getting started should give readers a quick win before going into the long-term stuff 15:50:00 I totally agree with that 15:50:14 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 because one playbook becomes a dozen very quickly 15:51:43 #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 Ok moving on to EEs 15:52:02 no, I think that is a misinterpretation 15:52:08 #undo 15:52:08 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 ok give it a summary don 15:52:18 the folder structure content doesn't belong at the end 15:52:29 my summary was earlier 15:53:05 oh, sorry. do you mean with the hashtag for the minutes? 15:53:30 you disagreed with my summary so yes, please summarize first. then wwhen we agree, we add to minutes 15:53:53 keeping in mind we still need to cover EEs 15:54:27 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 there shouldn't be any separate folder structure content 15:55:12 ok not sure I agree then 15:55:23 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 I do understand wanting to get the folder structure correct, I disagree that it belongs sprinkled within the hello world example 15:55:44 start simple, build up 15:56:15 let me just keep working with jklech on it and it'll get there 15:56:15 that PR is a pretty big changeset, it might be easier to discuss as 2 or 3 PRs 15:56:17 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 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 then show mkdir /path/to/playbooks_dir and mv ./my_first_playbook.yml /path/to/playbooks_dir/ 15:58:54 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 2nd PR does...the folder structure "somehow" and we can see that clearly to review 15:59:35 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 I can hang around 16:00:11 but that's another I think we should wait until we have something solid to review 16:00:22 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 heh ok thanks! 16:00:43 https://github.com/ansible/community-docs/tree/main/execution_environments 16:01:17 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 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 I think there were two ideas - 16:02:07 1 - add it to the user guide somewhere 16:02:16 2 - add it to the getting started guide 16:02:24 is that about right Don Naro ? 16:03:38 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 and 2 is really about extending the existing getting started and building on the hello world 16:04:11 yeah I think you me and andersson007_ did finally agree it's more of a quick start/getting started for EEs? 16:05:29 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 I can see it in the same area, but being specifically 'Getting started with EEs' so to speak 16:06:26 I feel like EEs are an intermediate/advance ansible user person. 16:07:30 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 that tutorial also shows how to use a collection pretty well too 16:08:43 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 ok sounds like we are in agreement 16:09:20 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 does that sound right? 16:09:46 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 that sounds right to me 16:10:17 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 it's not dependent but the two will fit together nicely 16:10:56 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 and it goes below ^^ 16:12:18 | Ansible Getting Started 16:12:18 |-- Getting started with Ansible 16:12:18 |-- Getting started with execution environments (or whatever title works best) 16:12:22 like that? 16:12:25 yeah 16:12:27 yeah 16:12:36 #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 ok cool. In case anyone else is around 16:12:52 #topic Open Floor 16:13:09 anhyone have anything else to bring up? and thanks for hanging around extra for this today! 16:13:28 nothing from me, thanks 16:13:53 #endmeeting