16:00:20 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:00:20 <zodbot> Meeting started Tue Nov 30 16:00:20 2021 UTC.
16:00:20 <zodbot> This meeting is logged and archived in a public location.
16:00:20 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:00:20 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:00:20 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:00:27 <samccann> #topic opening chatter
16:00:33 <samccann> ok who's around to talk the docs?
16:00:41 <ariordan> o/
16:00:53 <samccann> @room Meeting Time!
16:00:56 <felixfontein> o/
16:01:06 * samccann ponders if that worked
16:01:13 <samccann> #chair felixfontein
16:01:13 <zodbot> Current chairs: felixfontein samccann
16:01:31 <samccann> #chair ariordan
16:01:31 <zodbot> Current chairs: ariordan felixfontein samccann
16:02:08 <gwmngilfen-work> ello
16:02:53 <samccann> andersson007_: deric.crago dmsimard gundalow tadeboro briantist - around to talk docs?
16:03:02 <samccann> #chair Gwmngilfen
16:03:02 <zodbot> Current chairs: Gwmngilfen ariordan felixfontein samccann
16:03:04 <acozine> I'm half-here
16:03:17 <samccann> #chair acozine
16:03:17 <zodbot> Current chairs: Gwmngilfen acozine ariordan felixfontein samccann
16:03:36 <samccann> since #cushion acozine doesn't work
16:03:50 <samccann> #topic Action Item Review
16:04:20 <samccann> #info Ansible 5 goes out today...and so will the docs!
16:04:36 <samccann> #info agenda  -https://github.com/ansible/community/issues/579#issuecomment-976929469
16:05:12 <samccann> Any other action item updates?
16:05:47 <samccann> I lost track where we are with expand/collapse. I think I need to rebase to pick up the most recent requirements and then retest. Anyone remember anything else on that one?
16:06:27 <acozine> I was hoping for better styling on the expand/collapse thing
16:06:42 <samccann> ah yes. I think that was in the comments?
16:06:48 <acozine> right now it's easy to scan the page when the long stuff is collapsed and not realize there's anything there to expand
16:07:18 <samccann> #info for expand/collapse Pr - need to rebase and then attempt some better formatting because a reader may not even notice there is a collapsed section there.
16:07:25 <samccann> cool thanks!
16:08:07 <samccann> #action - rebase and improve visibility formatting for collapsed version of expand/collapse pr https://github.com/ansible/ansible/pull/75695
16:08:29 <samccann> ok gonna swing to something new
16:08:37 <samccann> #topic setting docs priorities for 2022
16:08:55 <samccann> It's that time of year!
16:09:18 <samccann> I listed some ideas of biggish items we could consider tackling. I'd like us to maybe agree on priority. which is the first, second, third?
16:09:28 <samccann> open to other ideas too, but that's what came to mind
16:10:29 <felixfontein> I'd rank responsiveness and semantic markup quite high, but I'm not really neutral :)
16:10:30 <samccann> #info we have test docs and community docs that need heavy work. Then navigation/toc/general findability. Search has problems. Scenario guides still going stale
16:10:47 <samccann> Yeah I had thoughts on that as well for later
16:11:35 <samccann> responsivness PR I think we are close on, semantic markup is sucked into a black hole for 6 months
16:11:59 <felixfontein> for the last 6 months, or for the next 6 months?
16:12:08 <acozine> heh, both
16:13:11 <samccann> #info we need to move forward on responsiveness and semantic markup
16:13:27 <samccann> So do we feel that is the top priority?  What is priority #2 then?
16:14:06 <acozine> I might vote for getting search set up so users can either search modules-only or search no-modules
16:14:30 <samccann> over integrating all the community docs that the community team has in a separate repo?
16:14:53 <acozine> hm, well they are different kinds of work
16:15:00 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:15:31 <samccann> The point here is we are extremely short staffed... so let me reword this
16:16:02 <samccann> what should ariordan and I focus on?
16:16:15 <samccann> And what should we as the DaWGs team try to recruit others to help us with?
16:16:17 <ariordan> Is searching within a specific version in the scope of "search improvements", or is it a separate issue?
16:16:34 <gwmngilfen-work> shouldn't you run a new survey and then decide that? :D
16:16:35 * gwmngilfen-work ducks
16:16:39 <samccann> It's all part of search improvements ariordan yeah
16:17:04 <samccann> hehe well Gwmngilfen a number of these came from the LAST survey
16:17:23 <samccann> which is why I'm reluctant to run another. Some items we addressed, a number we haven't touched yet
16:17:51 <gwmngilfen-work> i know, i know. more seriously, whatever the decision, make sure it goes into newsbot so people know about it
16:18:03 <samccann> #info on search - we should try for faceted search that includes version and module vs non-module search results
16:19:08 <samccann> any other opinions on priority? So far semantic markup etc and search seem top. gundalow mentioned before he felt community docs are also important (integrating what is in that separate repo)
16:19:54 <samccann> #info community team would like their community docs repo better integrated with docs.ansible.com
16:20:51 <samccann> ok moving on, and thanks!
16:20:53 <samccann> #topic semantic markup
16:21:06 <samccann> #info created an internal to Red Hat tracking ticket for the downstream impact
16:21:17 <samccann> so on to the brainfart I had on this one
16:21:30 <samccann> gonna ping bcoca in case he's around
16:21:51 <samccann> Could we just strip the new semantic markup out of `ansible-doc --json` and call it a day?
16:22:05 <samccann> So it's avialable only to the docsite and noplace else?
16:22:31 <felixfontein> I don't think that's a good idea
16:22:53 <felixfontein> a) it's a lot of work, and b) then there will be no more way to actually get hold of the real documentation included with the module/plugin
16:23:09 <felixfontein> (except by re-doing what ansible-core internally does to get hold of that info)
16:23:33 <samccann> ok brainfart option 2 - is there a way to do `ansible-doc --enhanced` where it shows up there?
16:24:01 <samccann> I'm trying to figure out a way to decouple this from downstream work. Otherwise, yes, it will be another 6 months easily before we can implement.
16:24:15 <felixfontein> of course it's possible, but I think the costs are too high
16:24:28 <samccann> as I see it, once it's there, collection folks will use it and it will impact these other RH products
16:24:37 <samccann> heh ok good to know
16:24:46 <felixfontein> what exactly is the problem with downstream?
16:24:55 <samccann> nobody answering
16:25:23 <samccann> we've been bugging The Powers That Be for months but get ..erm... yeah, not much
16:25:29 <felixfontein> ok, in tat case I would say screw them and just implement the changes upstream
16:25:36 <samccann> heh
16:26:29 <felixfontein> seriously, ignoing a proposal should be equivalent to accepting it
16:26:58 <felixfontein> so if you don't say anything after having been made aware of it multiple times and having had half a year to respond, it's your own fault if you don't like it and never said it
16:27:11 <samccann> We have that proposal yeah, and again, not getting much. But if the Ansible steering committee approves it, maybe then it can go forward?
16:27:38 <felixfontein> I hope so :)
16:28:07 <samccann> Well, I can push further internally, and coordinate with gundalow and maybe sivel for advice on how to move this foward.
16:28:56 <samccann> #action @samccann to push more on the community and internal RH tickets for semantic markup decisions
16:29:20 <felixfontein> I'll try to get feedback by the steering committee tomorrow (and async)
16:29:34 <samccann> that would be great, thanks!
16:30:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:30:08 <felixfontein> thanks as well for continuing to try to get feedback :)
16:30:15 <samccann> #topic responsive plugin tables
16:30:28 <samccann> #link https://github.com/ansible-community/antsibull/pull/335
16:30:53 <samccann> I thought we were either close or ready to merge on that one?
16:31:27 <bcoca> i was summon3ed? starting backlog read
16:31:42 <felixfontein> I guess the main open question is whether the plugin config column should be a separate column or whether it's ok combined with the description column
16:32:25 <samccann> bcoca: nevermind. my idea was bad anyway
16:32:27 <bcoca> i can add --strip-markup option
16:32:56 <felixfontein> bcoca: it would need to be --convert-markup-from-new-to-old-format and be enabled by default, I guess
16:33:00 <bcoca> we already have the function that strips markup (for screen presentation)
16:33:01 <samccann> felixfontein: did you hear strong feedback for keeping it separate?
16:33:23 <bcoca> felixfontein:  convert? i thought we were adding to markup, not changing it
16:33:42 <felixfontein> samccann: I haven't heard anything about it for some time now :) but when we were more actively discussing it here, I think some people mentioned that, but I'm not sure whether they still think so
16:33:57 <bcoca> imho if people dont want the markup info, they can strip themselves, but i would still return it with --json version
16:34:04 <felixfontein> bcoca: the markup does change for some things, like instead of I(k=v) the new format would be O(k=v)
16:34:16 <felixfontein> bcoca: I agree
16:34:32 <felixfontein> bcoca: the main idea was that other programs which rely on the old markup don't need to be changed
16:34:57 <bcoca> well, they can stay w/o change, but wont benefit from new markup and maybe 'literally' display it
16:35:08 <felixfontein> though I think by not providing any feedback to the proposal we shouldn't really invest so much work for them, and that no feedback means "I agree with all changes"
16:35:12 <samccann> felixfontein: well I'm +1 for merging as is and gathering feedback. I 'think' we use the most recent antsibull for devel docs but not for /latest/ - so we can let it sit on devel for a couple of months and see what people think
16:35:47 <felixfontein> samccann: sounds good. I'd have to make a new release so that it will get used for devel though.
16:36:01 <samccann> bcoca: that 'literally' display it is my worry and what I can't get an answer on from galaxy-ng etc. But maybe I'm just not nagging the right people
16:36:06 <felixfontein> but are you sure about the part that `latest` doesn't use the latest released version as well?
16:36:43 <samccann> yeah just don't do it today felixfontein since Ansible 5 releases?
16:37:03 <felixfontein> hehe :) I guess merging it today is fine, but not releasing ;)
16:37:41 <felixfontein> also the next 5.x.y release is 5.1.0 in ~four weeks, so even if the latest antsibull release is used for `latest`, it will be four weeks until that happens
16:37:43 <samccann> #action samccann_ to verify /latest/ publication uses known-good requirements file and /devel/ uses requirements.txt with an open antsibull version
16:37:50 <samccann> sounds good.
16:38:11 <felixfontein> (it might be used for the 4.10.0 release though that's up next week)
16:38:30 <samccann> felixfontein: problem is, if someone sez' update latest to grab this thing we forgot'... it will get updated before then
16:38:31 <felixfontein> ok, in that case I'll merge that now, and create a release tomorrow or so once the docsite is published
16:38:45 <samccann> and yep every dot release for every maintained ansible version
16:38:53 <felixfontein> true
16:38:54 <samccann> cool thanks
16:39:24 <felixfontein> next week will also be the ansible-core 12.1.0 release IIRC
16:39:53 <samccann> yep it all just keeps on keepin on
16:39:59 <felixfontein> yep
16:40:15 <samccann> in fact I'll have to check if they've frozen backports yet as Ansible 5 docs require 2 backports to work
16:40:31 <samccann> ok moving on...
16:40:33 <felixfontein> I think they are, since there was an email about RCs a bit earlier today
16:42:03 <felixfontein> oh, zodbot was gone
16:42:06 <gwmngilfen-work> do i summarise correctly that we have rough approval and now we need to flesh out an implementation of some kind?
16:42:28 <gwmngilfen-work> i think felixfontein's schema looked decent, though I need to go back and review it
16:42:51 <felixfontein> gwmngilfen-work: the schema was an ad-hoc proposal, a review would definitely be good :)
16:42:55 <samccann> Do either of you have links handy?
16:43:10 <felixfontein> with that proposal we would also get the 'Edit in GitHub' back working (for repos which opt-in)
16:43:24 <samccann> to either the proposal or the schema?
16:43:28 <felixfontein> https://gist.github.com/felixfontein/18b1763ca2a5320808225c4121b50791
16:43:41 <felixfontein> this is my schema proposal
16:44:20 <gwmngilfen-work> right, "edit me" is definitely a link type
16:44:36 <gwmngilfen-work> ok, let me get a schema review in, and then we can pick it up from there?
16:44:42 <bcoca> felixfontein: i would keep this in the galaxy.yml
16:44:46 <felixfontein> it's a different kind of link though, since it is placed somewhere differently :)
16:45:00 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:45:02 <gwmngilfen-work> #action gwmngilfen to review the proposed schema
16:45:04 <bcoca> as this is info that galaxy/ah/hub would also benefit from (except maybe edit on github)
16:45:24 <bcoca> iirc, there is already some overlap
16:45:33 <felixfontein> bcoca: is it that simple to add new fields to galaxy.yml? or will it break all kind of things until they explicitly support the new fields?
16:47:31 <felixfontein> bcoca: I mainly remember the problem with meta/main.yml for roles; I'm not sure I ever looked at how galaxy.yml resp. MANIFEST.json is handled by ansible-core itself or by the galaxy importer
16:47:43 <gwmngilfen-work> i have no particular pref as to where the info lives, so if it can safely go in galaxy.yml then thats fine with me. I just care that it's maintainer-defined
16:49:41 <samccann> so to add it directly to galaxy.yml requires core approval as part of 2.13, right?
16:49:49 <felixfontein> I don't care either, I'm just not sure whether we want to pollute galaxy.yml / MANIFEST.json with this (and whether this actually requires modifications to ansible-core so that info ends up in MANIFEST.json)
16:50:16 <felixfontein> samccann: probably yes, and in particular this has to wait for Ansible 6 and cannot be done in Ansible 5.x already
16:50:35 <gwmngilfen-work> well at least that gives us time to research it ;)
16:50:39 <felixfontein> assuming that ansible-core doesn't just include everything from galaxy.yml in MANIFEST.json (which I guess it does not)
16:50:41 <bcoca> also note that there was plan that galaxy/AH becomes the main docsite for collections info
16:51:08 <bcoca> so if doing this to expand on docs, i would closely coordinate with galaxy team
16:51:22 <felixfontein> bcoca: I heard about that, but I never heard anything more specific, and nobody from galaxy team ever showed up in the docs meeting IIRC
16:52:08 <samccann> heh
16:52:10 <felixfontein> the scenario guides etc. probably won't work with galaxy/AH either, since they are RST based
16:52:34 <samccann> So next steps other than Gwmngilfen reviewing the schema?
16:53:39 <gwmngilfen-work> i think thats the main thing
16:53:55 <gwmngilfen-work> i'll do that this week
16:55:13 <bcoca> felixfontein: i doubt they know this meeting exists
16:55:27 <samccann> this feels like it's slipping into the semantic markup black hole of needing multiple teams buying into it if we put it in galaxy.yml
16:56:01 <bcoca> that is the problem with docs now, since 100 teams claim ownership
16:56:48 <gwmngilfen-work> thats fair. i'm going to assume its a new (optional) file for the moment since that wont break anything - easier to work that way and move it to galaxy.yml later if needed
16:56:55 <felixfontein> as long as there is something called the 'docs team', that one should have ownership of docs...
16:58:36 <samccann> ok anything else on this before we open the floor?
16:58:58 <bcoca> felixfontein: several reasons that might not make as much sense as you think, but i disagree with 1/2 and im not going to go over them all
16:59:33 <samccann> #topic Open Floor
16:59:42 <bcoca> initially 'docs' team was created to review and polish the docs, ended up with ownership of build (which they didnt have resources for, so ended up in community ...)  the history of it gets really murky
16:59:55 <samccann> Okay last call - anyone have a topic to bring up? A pr or issue to push forward on?
16:59:59 <bcoca> in general they also own tower/awx/AAP in general
17:00:41 <samccann> felixfontein: the only 'docs team' is the internal one for AH etc. But yes, it's possible given the complexities of all this, we may need to push ownership to them.
17:01:09 <samccann> won't speed anything up. But will have someone who can wrangle cats better than I am right now
17:01:16 * bcoca expects this to end up in 'docs comitee' with 10 teams represented
17:01:35 <felixfontein> I'm once again glad I don't work in a large company...
17:02:13 <bcoca> s/company/project/ ... growth/success brings in complexity of communication and coordination, its not exclusive to a crop
17:02:15 <bcoca> corp
17:02:35 <samccann> bcoca: lol I TRIED on a docs committee but got no where
17:02:38 <samccann> heh
17:02:40 <felixfontein> I first read 'crap', and suddenly the sentence got a slightly different meaning :)
17:02:54 <samccann> yeah other than airing our dirty docs laundry, any other open floor items?
17:02:57 <bcoca> samccann:  im shocked, seems currently it is the solution for all overlaps
17:03:14 <bcoca> felixfontein: corp/crap .. tend to be synonims
17:03:30 <bcoca> now 'enteprise' is a dirty word in my dictionary
17:03:32 <felixfontein> bcoca: I guess you know better, since you have more experience :)
17:03:42 <bcoca> ;-p
17:03:43 <samccann> ok gonna close out the meeting so we aren't saving this in the meeting log forever ;-)
17:03:47 <samccann> #endmeeting