15:01:20 <samccann> #startmeeting Documentation Working Group aka DaWGs
15:01:20 <zodbot> Meeting started Tue Mar 28 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:32 <samccann> @room Meeting time! Who is here to talk the docs?
15:01:34 <felixfontein> o/
15:01:39 <oranod> o/
15:01:43 <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:55 <samccann> #chair felixfontein Don Naro
15:01:55 <zodbot> Current chairs: Don Naro felixfontein samccann
15:01:56 <oranod> hey felixfontein
15:02:05 <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 <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:27 <samccann> briantist: - around to talk docs today?
15:04:32 <samccann> official agenda is at  https://github.com/ansible/community/issues/678#issuecomment-1468603478
15:04:49 <samccann> We'll skip action items because we don't have any open ones this week
15:05:10 <samccann> There are a bunch of topics today, so we'll start based on urgency (in my head anyway)
15:05:18 <samccann> #topic Semantic markup enhancments
15:05:26 <samccann> felixfontein: want to give this one a go?
15:06:06 <samccann> it's based on this PR - https://github.com/ansible/ansible/pull/80240
15:07:10 <felixfontein> sure
15:08:08 <felixfontein> ansible-core 2.15 will be the first ansible-core version to support semantic markup! but this also means that if a collection uses semnatic markup, and you look at its documentation (in ansible-doc) with an older ansible-core version, then semantic markup won't be rendered correctly
15:08:36 <felixfontein> that's why I would suggest to not advertise semantic markup *too much* by only adding the documentation to devel, but not the stable-2.15 branch
15:08:57 <felixfontein> which means that the ansible-core 2.15 / Ansible 8 docsite won't have that information, while the devel docsite will have it
15:09:37 <felixfontein> this is probably also relevant since some tooling doesn't support semantic markup yet, like AH, the network team's docs generator, and xlab's docs generator
15:10:22 <samccann> ok valid points, yeah
15:10:40 <samccann> I tend to agree - we hold that PR open for another week or so (until after the branch pull) and then merge
15:10:51 <felixfontein> delaying the 'official' (stable) docs by one major release (i.e. ~6 months) would give these projects more tie
15:11:26 <samccann> +1 from me. anyone else have opinions?
15:12:43 <samccann> silence is golden
15:13:07 <felixfontein> indeed :)
15:13:21 <samccann> So we are all set with the current antsibull-docs PR? I think matt had a comment last night but I haven't checked. is that ready to merge?
15:14:13 <felixfontein> that one already has been merged
15:14:27 <samccann> heh ok cool
15:14:36 <felixfontein> the only one missing is an ansible-doc PR for role support which is waiting for a review from bcoca (https://github.com/ansible/ansible/pull/80305)
15:14:40 <samccann> anything lingering wrt the roles semantic markup?
15:14:46 <samccann> ah gotcha cool
15:15:06 <oranod> so when you say delaying the official stable docs by one major release, what does this mean in effect?
15:15:26 <samccann> it means hinding the docs that talk about it, but collections 'in the know' can still implement it
15:15:46 <samccann> so if felix modifies his collections, we have a few to make sure things work before opening the flood gates so to speak
15:16:07 <samccann> but the docs will show up on devel
15:16:29 <samccann> #info semantic markup is ready to go and antsibull-docs update pr already merged
15:16:39 <felixfontein> yes... then we have some example collections using it, some tools that work fine with it (including ansible-core 2.15's ansible-doc and the docsite), so there is some motivation for others to also implement this :)
15:16:45 <samccann> so that's the final antsibull-docs update for 2.15 unless there is a bug
15:17:43 <felixfontein> yes
15:17:46 <samccann> #agreed - we will not post docs about how to use semantic markup  in 2.15 but docs will appear on devel. This gives time for other projects to catch up
15:17:57 <samccann> anything else on semantic markup before we move along?
15:18:02 <samccann> 🎊
15:18:11 <samccann> cuz this is a big win imo!
15:18:37 <felixfontein> antsibull-docs will probably continue with a 2.0.0 version, and the stable-1 branch will cover what's currently used for ansible-core 2.15 / Ansible 8, i.e. if bugfixes need to be added later they can easily be added to a 1.11.x, while new features end up in 2.x.0
15:18:45 <felixfontein> no, I think that's it!
15:18:54 <felixfontein> thanks to everyone who helped getting through with this :)
15:19:05 <samccann> sounds like a plan stan
15:20:18 <samccann> #topic jinja docsite
15:20:28 <samccann> time for your fun Don Naro !!
15:21:15 <felixfontein> \o/
15:21:36 <oranod> #info we have an mvp (minimum viable project) of the new docsite for Ansible community
15:21:46 <oranod> #link https://ansible.github.io/jinja-docsite/
15:22:04 <oranod> thanks especially to you samccann and felixfontein for helping the effort get this far
15:22:24 <oranod> I had a great time with that js toggle felixfontein
15:22:45 <felixfontein> cool :)
15:23:45 <oranod> anyway we're at the point now where we have content parity with the current docsite over on docs.ansible.com and all the other components we talked about are in place, namely the feedback text and toggle button
15:23:57 <oranod> I don't believe we have any regression or other sort of blocker that would cause loss of a user being able to navigate to docs
15:24:28 <oranod> so from here on it's just making enhancements and iterating over whatever feedback rolls in
15:25:05 <oranod> https://github.com/ansible/jinja-docsite/labels/Review
15:25:20 <oranod> starting to tag feedback issues with the review label
15:25:47 <samccann> curious - review instead of feedback?
15:25:51 <oranod> #info Need to identify the next steps to move forward with this and take over docs.ansible.com
15:26:07 <oranod> yeah I just thought feedback that comes out of some kind of review
15:26:18 <oranod> I'm not too fussed about the label
15:26:21 <samccann> so for me, a next step would be broadening the 'reviewers' so to speak. We know about it, and the community WG and people who pay attention to the bullhorn etc.
15:26:47 <samccann> Give em a week to scream (aka if someone finds a blocker) and then go live?
15:27:17 <oranod> what do we think would constitute a blocker here?
15:27:20 <samccann> it has the toggle so people can go back and forth 'for a time' anyway. Alas, I lost my web analytics which is REALLY bugging me so I dunno how we can tell who's going back to the old way so to speak
15:27:43 <samccann> So for example, if we made an unholy heck out of the controller pages
15:28:14 <oranod> the only thing that has changed there is the layout - from cards to grid
15:28:42 <samccann> oh I agree with you for sure. But a few more people banging on it might find a hole we didn't think of.
15:29:15 <samccann> and I think we, the DaWGs team, decides what is a blocker vs what gets fixed over time so to speak
15:30:13 <samccann> also, it gives a broader set of people time to stew on it and give feedback. That's why I wanted to give it a week and then flip the switch
15:30:45 <samccann> tho we have to untangle jenkins builds in the meanwhile so they will publish the jinja version of those pages, not the old stuff.
15:30:47 <oranod> yeah but we have been putting this out in the bullhorn for several issues in a row. so I feel like we're just saying to wait until we ask in other channels here and in places like reddit before going live.
15:31:00 <samccann> yeah that's what I'm saying.
15:31:53 <samccann> I don't feel even RH internal peeps have taken a good look (controller folks). And I dunno if the bullhorn covers users? Maybe it does? cybette if you are around ??
15:32:45 <samccann> and I'll be honest, we didn't do this for the last update, when we went from small teal boxes to big white boxes so to speak.
15:32:55 <samccann> so maybe I'm just being too fussy here?
15:33:02 <oranod> I appreciate the need to err on the side of caution but, at the same time, feedback so far has been really light. maybe it's worth seeing if casting a broader net for a week gives us more opinions and uncovers something but my true feeling is that it's just going to delay things.
15:34:23 <oranod> what about if we hit matrix and reddit this week, as well as highlight it as the community WG meeting to see if anyone objects, then flick the switch next Monday or so?
15:34:34 <samccann> sounds good to me
15:35:07 <oranod> that'll give a bit more time to do polishing based on the review issues so far
15:36:15 <oranod> actually I'll be out early tomorrow then on PTO for the rest of the week. maybe I'm bad at planning these things. how about if we do those things and then decide to flick the switch after the next DaWGs?
15:36:56 <felixfontein> sounds good to me as well
15:36:57 <oranod> give everyone here a bit more time
15:37:56 <oranod> I wouldn't mind hearing more thoughts from acozine if she's about. I'd like to know if her concerns from early review have been addressed.
15:38:27 <samccann> She is back from vacation this week so yeah, good timing on  that
15:39:39 <samccann> #agreed we will broadcast the call for testing  the prototype docsite this week and then flip the switch on docs.ansible.com Monday
15:40:37 <oranod> sorry, just to be clear. maybe we can flip the switch Tuesday after this meeting.
15:40:52 <samccann> #undo
15:40:52 <zodbot> Removing item from minutes: AGREED by samccann at 15:39:39 : we will broadcast the call for testing  the prototype docsite this week and then flip the switch on docs.ansible.com Monday
15:41:29 <samccann> #agreed - we will broadcast a call for testing the prototype docsite this week and flip to these pages on docs.ansible.com on Tuesday after DaWGs final decision
15:41:35 <samccann> there we go!
15:42:05 <oranod> sweet. thanks samccann
15:42:28 <samccann> anything else before we rapidfire on a few other topics?
15:42:54 <oranod> one final thought on the "go live" plan - should we move all the bits including the build workflow etc over to `ansible/docsite`?
15:43:40 <samccann> that would make the jenkins integration easier since it builds from there
15:43:43 <oranod> know what I mean? I could set things up to use nikola and do all the build and deploy stuff from that repo and we get rid of the jinja-docsite
15:44:12 <oranod> unfortunately we'll still need jenkins for a bit longer to get the html over to the web server
15:44:22 <samccann> let's create some issues to track this after this meeting
15:44:37 <oranod> sounds good. let's move on.
15:45:05 <samccann> #action samccann oranod create issues to track moving jinja2 docsite to ansible/docsite and any jenkins changes
15:45:14 <samccann> #topic Documentation updates
15:45:31 <samccann> #info  Do we as community support additional install instructions - https://github.com/ansible/ansible/pull/80308 ?
15:45:40 <samccann> #info note we removed this page a year ago because core team only verifies pip installs. Someone else added a few more on this page, and now it seems to be growing to be what it was before... we removed it.
15:46:10 <samccann> basically the people who initially started the extra page... no longer participate here (which was always the risk)
15:46:40 <oranod> yeah some of this seems like it's third party. like documenting various package managers.
15:46:51 <samccann> I want to say the initial additions were for.. erm.. PPA stuffs? which is active on the packaging channel here
15:47:24 <samccann> but we've strayed from that and I'd like us to consider what we want here before we end up with another dumping ground page that gets outdated and nobody knows how to fix it etc
15:47:39 <samccann> also possible this should go to the community WG?
15:49:13 <felixfontein> sounds lika a good idea
15:50:02 <oranod> perhaps. I was looking at this PR earlier and approved given that there was an apt install section. but it'd be good to keep this from another dump. I was also thinking about finding the order for these instructions - should suse go before ubuntu? should it be alphabetical? what happens when there is some outlier procedure that adds more complexity?
15:50:38 <samccann> yeah I don't want anything on that page that the community WG isn't going to keep valid so to speak
15:50:41 <oranod> the risk of taking on the sea to drink is strong here so it'd be good imo to get a WG decision on limiting install doc to what is verified
15:50:54 <samccann> should I open a community topic?
15:51:05 <felixfontein> :+1:
15:51:40 <samccann> #action samccann open a community topic to decide which packages go on the non-pip install docs page
15:51:54 <cybette_> Sorry for the late response, having dinner. The Bullhorn is mainly advertised as developer/contributor newsletter so will not reach a wide user base.
15:51:58 <cybette_> I think waiting a week until next week's meeting is good, in the meantime if you want to post in Reddit I can pin the topic for visibility. Or I can do the Reddit post, either way just let me know.
15:52:14 <samccann> #info we want the install instructions to be maintained so will ask the community WG for advice
15:52:31 <cybette_> (apologies for being in the wrong topic as well)
15:52:46 <samccann> thanks cybette ! I'm happy to post it in reddit but a pin might be nice as well
15:52:55 <samccann> no worries lol
15:53:03 <samccann> Meanwhile another in this vein of what do we want to do
15:53:05 <samccann> How do we determine what goes on Tools page? - https://github.com/ansible/ansible/pull/80263
15:53:54 <samccann> I don't know that i've ever restricted what gets posted there. But also, I think not a lot of PRs come in. So, do we just merge willy-nilly? or some kind of control on what we think are recommended tools ?
15:54:35 <oranod> we should probably also clean that up a little because some tools are no longer maintained, like atom
15:54:36 <samccann> it's this page - https://docs.ansible.com/ansible/latest/community/other_tools_and_programs.html
15:55:02 <samccann> yeah so who decides what goes there?
15:55:06 <oranod> I thought it was fair enough to include the intellij plugin for lint there because some people might actually be using that
15:55:57 <samccann> and, could we point these PRs to https://github.com/jdauphant/awesome-ansible and say ask there?
15:56:24 <oranod> I think it would be good to have Ansible helper tools and things in that page but maybe remove some of the more generic parts, like the list of editors
15:56:49 <felixfontein> I guess antsibull-changelog and antsibull-docs could be added to that list
15:57:21 <samccann> feels like we need to decide the purpose and scope of that page. I mean what's stopping everyone from wanting to add to it?
15:57:26 <felixfontein> yep
15:57:39 <samccann> not that the floodgates have opened but we need some review process and guidelines imo
15:58:24 <samccann> as for the editors, some of them have add-ons for ansible, so that seems relevant to highlight which ones have that
16:00:16 <samccann> So perhaps the next step on this one is just to say it needs at least two technical review/approvals before we merge?
16:00:27 <samccann> or should it again be a community WG decision?
16:00:29 <cybette_> I think maintenance is key, if I'm looking through docs on main ansible site I would expect the tools mentioned to be maintained
16:01:24 <samccann> yeah see, I agree.. but also - maintained by whom? Do we only post tools maintained directly in this community (like antsibull-docs etc and vscode plugin) or maintained in the general sense (like not dead like the atom editor is now)
16:01:31 <felixfontein> I would expect the same for installation methods - if we add more, we should monitor them whether they are regularly updated, and when not, remove them
16:01:56 <felixfontein> yeah, figuring out whether something is maintained or not isn't easy
16:02:13 <cybette_> Yeah
16:02:19 <samccann> ok maybe I'll just poke up another community topic for discussion on this one - what to post on the  tools page etc
16:02:28 <samccann> cuz we're at the top of the hr (and a bit)
16:02:48 <samccann> #action samccann to post community-topic on what stays or goes on tools docs page
16:02:54 <felixfontein> :+1:
16:02:54 <samccann> #topic Open Floor
16:03:03 <samccann> Any lingering items to discuss today?
16:03:14 <samccann> anyone lurking who wants to bring something docs related up?
16:04:41 <samccann> silence is godlen
16:04:45 <samccann> GOLDEN lol
16:04:53 <samccann> #endmeeting