16:01:27 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:01:27 <zodbot> Meeting started Tue Mar 15 16:01:27 2022 UTC.
16:01:27 <zodbot> This meeting is logged and archived in a public location.
16:01:27 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:01:27 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:27 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:01:43 <samccann> #chair acozine felixfontein
16:01:43 <zodbot> Current chairs: acozine felixfontein samccann
16:01:53 <samccann> #topic opening chatter
16:02:00 <samccann> @room Meeting time! Who is here to talk the docs?
16:02:08 <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!
16:02:18 <acozine> o/
16:02:30 <acozine> oh, I'm already furniture
16:02:42 <samccann> andersson007_: briantist around to talk docs?
16:02:43 <samccann> heh yep.
16:03:26 <samccann> Official agenda is at https://github.com/ansible/community/issues/643#issuecomment-1062085161
16:05:07 <samccann> #topic Documentation updates
16:05:21 <samccann> #info Meeting time will say the current UTC until Europe goes to DST (March 27th) so for those in the US, this meeting will be one hour later for another week
16:05:36 <samccann> and here's a fun new one - #info proposing we archive docs for EOL releases - see https://github.com/ansible-community/community-topics/issues/78
16:06:42 <samccann> tldr - we talked to our resident search expert and the best way to de-emphasize older EOL docs from search engines is to use permanent redirects. I'm not comfy just redirecting 2.4 users to latest, so we'd have to do that in tandem with setting up an archived docsite
16:06:46 <acozine> ooh, this sounds interesting
16:07:46 <felixfontein> hmm, but permanent redirects mean that the old content has to go
16:07:57 <acozine> would we have confirmation pages, then? something like "you're trying to access an ancient version of the Ansible docs" with the option of "yes, look at 2.4 on our archive site" or "no, go to the more recent docs"?
16:08:00 <samccann> the old content would 'move'
16:08:09 <felixfontein> acozine: that's not compatible with permanent redirects
16:08:15 <samccann> @acozine  - no. I dunno how to do that
16:08:20 <samccann> we would first:
16:08:24 <acozine> mmm, true
16:08:35 <samccann> 1 - publish 2.3 to docs.ansible.com/archive/ansible/2.3
16:08:53 <samccann> 2. - put in redirects so all access to the old 2.3 would go to latest
16:09:14 <samccann> 3. add a sentence to 'latest' banner to point to new archives site for all EOL docs
16:09:21 <samccann> or something like that
16:09:22 <felixfontein> samccann: but that would mean that users that intentionally go to an existing 2.3 link end up on latest, and have a hard time figuring out where to actually find the 2.3 docs?
16:09:34 <samccann> yes
16:09:46 <samccann> but if they search 'ansible 2.3 docs' they would get the archive site
16:09:57 * gwmngilfen-work is here, finally
16:10:09 <samccann> #chair Gwmngilfen
16:10:09 <zodbot> Current chairs: Gwmngilfen acozine felixfontein samccann
16:11:18 <samccann> the goal is to prevent.. ahem.. 'modern' users of current releases from mistakenly landing on a very old doc page due to google etc
16:11:57 <samccann> while not removing docs entirely for those using EOL releases. So we move them to an archive site
16:12:16 <felixfontein> (sorry, was changing machine)
16:12:17 <samccann> then going forward, when a release goes EOL, their docs goes to the archive site (with say a month warning banner before it happens)
16:12:45 <acozine> so the "main" site would only have `latest` and `devel`?
16:12:57 <samccann> yes
16:13:11 <felixfontein> and 2.9 until may ;)
16:13:17 <acozine> heh
16:13:21 <samccann> heh. 2.9 is a problem child for sure
16:13:43 <felixfontein> not for that much longer...
16:13:50 <gwmngilfen-work> if it's May, then just wait a month before we change anything ;)
16:13:58 <gwmngilfen-work> it's hardly far out
16:14:15 <samccann> well the problem is - it's may for community, It's I don't know cuz I feel like it keeps changing... longer for RH support
16:14:54 <samccann> but I thought it was at least Nov this year, maybe even May next year, but don't quote me on it.
16:14:57 <felixfontein> ah, so 2.9 docs will stay around for much longer?
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:16 <samccann> I will doublecheck that one but I think so, yeah
16:15:31 <acozine> this will be a lot of work - is it proportional to the problem?
16:15:48 <samccann> ain't that the $64K question
16:15:59 <acozine> a lot of work and a lot of disruption, too
16:16:38 <samccann> as usual, I'll ask y'all to repeat your comments on the issue itself since those get far more eyeballs than this meeting gets
16:16:42 <samccann> async FTW!
16:17:17 <samccann> and yes, last time I tried, even with your excellent notes acozine, I couldn't even publish 2.3. So.. a lot of work.
16:17:38 <acozine> heh
16:17:48 <acozine> I guess you could rsync the HTML pages, maybe
16:18:50 <samccann> yeah I think gundalow mentioned something like that - just copy the existing html or something
16:19:48 <briantist> o/
16:19:52 <acozine> it's not like those docs are changing
16:20:08 <samccann> #chair briantist
16:20:08 <zodbot> Current chairs: Gwmngilfen acozine briantist felixfontein samccann
16:20:58 <briantist> just getting caught up
16:21:21 <acozine> I put a comment on the issue. I'm not opposed, but I think we need to be clear about the cost/benefit ratio.
16:21:24 <briantist> but couldn't we keep old docs where they are, and mark them with `robots.txt` or equivalent to not be indexed anymore?
16:21:26 <samccann> welcome
16:21:41 <samccann> that's what our search expert says we should NOT do
16:21:50 <briantist> interesting... I wonder whynot
16:21:56 <samccann> I can only attempt to paraphrase here, but it goes something like this
16:22:43 <samccann> those links come from 'high value' sites. (I think stackoverflow when someone sez that). If we deindex, we through away all that 'value' in terms of the authority of our docsite
16:23:02 <samccann> If we redirect, we retain that value/authority
16:23:19 <briantist> I see, that does make sense
16:23:34 <samccann> so gist of it is, if we just deindex it all, it hurts the authority of ALL docs.ansible.com
16:23:50 <samccann> so to speak. So we could see our google search results lower than they are today
16:23:53 <acozine> I wonder if we could put something into the version-switcher that link over to the archive site
16:24:10 <acozine> it probably wouldn't work for specific pages
16:24:14 <samccann> I dunno @acozine. Maybe
16:24:14 <acozine> and it probably would be one-way
16:24:48 <samccann> most likely I'd need to ask for community help with that. The code is fragile and someone with ACTUAL coding skills that aren't a decade old and rusty might be able to make it less fragile
16:24:53 <samccann> and yep, one way
16:26:15 <samccann> so what I've gotten so far is - this is okay but is it worth it given the hurdles to make it happen and then the long term need to maintain yet another docsite vs the two we have already (ansible and ansible-core)
16:26:24 <acozine> okay, i need to take a biobreak before my meeting at the top of the hour - same thing will happen next week, then once Europe changes time and we move the meeting, I'll be able to stay for the whole hour
16:26:31 * acozine waves
16:26:41 <acozine> er, meeting at the half-hour
16:26:44 <acozine> time is hard
16:26:48 <felixfontein> samccann: doy ou mean the code of the version switcher?
16:26:49 * acozine waves again
16:26:49 <samccann> heh ok thanks!
16:26:59 <felixfontein> bye acozine!
16:27:08 <samccann> felixfontein: yes - I originally hacked it from 'somewhere' and got it to work.
16:27:27 <samccann> but it works by scraping the url and replacing say 2.9 with latest etc
16:27:48 <samccann> it would require a longer replacement to get to archive
16:28:17 <samccann> and even if we did, which one do we go to? If we do this, we'll have 7 versions to start (2.3-2.9)
16:28:50 <samccann> or maybe we hardcode it to go to the archive docsite itself (a top-level html page) where the versions are listed. dunno
16:29:04 <felixfontein> I guess you would add all versions to the selector then (like `2.3 (archived)` or something like that to make clear it's archived)
16:29:24 <samccann> that's another option, to list them all out.
16:29:33 <felixfontein> alternatively have an 'Old versions archive' link beneath the version selector which sends you to the archive index
16:29:53 <samccann> ^^ would be the one I'd prefer. Less long-term maintenance.
16:30: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:30:09 <felixfontein> indeed!
16:30:12 <samccann> just one link 'somewhere' where the ever-growing list will be
16:30:23 <samccann> gah.. and I didn't info any of this
16:30:47 <samccann> #info we are considering moving EOL docs to an archive site to keep them available, but not in search results
16:31:26 <samccann> #info biggest question - is it worth all this effort and long term maintenance to create this archive site ? Are the older EOL docs causing that much problem in search?
16:32:02 <samccann> #info one of the search problem areas are for specific built-in modules - they are popular and have been for ages so search results can pick up very old docs for these
16:32:18 <samccann> #info please comment on the issue so we can track community feedback on this
16:32:23 <samccann> ok phew
16:32:53 <felixfontein> :+1:
16:33:03 <samccann> #info always looking for help on the backlog - issues - https://github.com/ansible/ansible/issues?q=is%3Aopen+is%3Aissue+label%3Adocs and PRs - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
16:33:14 <samccann> Okay we cn move onto another topic now
16:33:29 <samccann> #topic Versioned docs on collections
16:33:38 <samccann> This comment has interesting points - https://github.com/ansible-community/community-topics/issues/73#issuecomment-1065910561
16:34:31 <felixfontein> automatic validation is next to impossible in general anyway
16:34:51 <samccann> What I wanted to verify - if say community.general has a user guide in the collection - when we publish that, do we always pull from the collection version that matches the release? So x.y collection is in ansible 5 and has those docs, and x.z collection is in ansible 6 and has those versioned docs?
16:34:55 <felixfontein> a lot of collections need specialized services or hardware and you cannot validate examples for these by running the examples without having access to these services/hardware
16:35:33 <felixfontein> samccann: the /latest/ docsite matches the collection versions
16:35:35 <samccann> felixfontein: yeah that validation idea actually came about in the flip sense - some of the vmware docs examples are actually extracted from unit/integration tests in CI.
16:35:51 <felixfontein> so the guides in c.g in the docsite are from the same version the plugins/modules that the docsite documents are from
16:36:06 <samccann> cool. I figured that's the way it worked but wanted to verify
16:36:46 <samccann> as for collection /examples being in docs - that's something we could test out I guess
16:37:38 <samccann> sphinx/rst supports  including other files. So a user guide could include select examples (one by one) into the docs. The only thing I'm not sure about is if antsibull docs can handle this?
16:38:45 <felixfontein> it would need to be properly defined which files are copied where
16:39:02 <felixfontein> right now antsibull only copies .rst files from docs/docsite/rst/ that do not contain disallowed labels
16:39:13 <felixfontein> to make sure that no collection can accidentally break the docs build
16:39:31 <samccann> https://docutils.sourceforge.io/docs/ref/rst/directives.html#include
16:39:37 <felixfontein> if we copy more things, we need to make sure that these things cannot break the docs build or affect docs outside that collection
16:40:38 <samccann> so if antsibull can't or shouldn't reach outside of docs/docsite/rst/ do we want to suggest in that issue that the examples repo should live there as well? It makes it less obvious to someone just looking at the collection itself that there are examples tucked away there
16:41:54 <felixfontein> it depends a lot on what we want. the files in doc/docsite/rst be for direct consumption of humans or not?
16:42:36 <felixfontein> /examples is pretty much unstructured, so we would have to define how it should end up in the docsite build, and which parts of it
16:42:54 <samccann> so in my ideal world - a collection owner who WANTED to add examples could put them in one place (an examples directory somewhere). If they then decided, hey I have these spiffy examples, let me put them in docs, they would be able to do that w/o having to copy them
16:42:55 <felixfontein> for example assume that /examples contains a 1 MB executable file. do you want to have that included in the docsite?
16:43:31 <samccann> so for me, the examples wouldn't be in the docs unless someone uses the `include` sphinx directive in an rst file to add them.
16:44:18 <samccann> That wouldn't prevent someone from trying to add that 1MB executable file I suppose, but they would be doing it specifically with the include (and would break the docs build)
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:20 <felixfontein> so antsibull would have scan the .rst files for `.. include::` statements, figure out where to find these files, and copy them over?
16:45:48 <samccann> well we could do it one of two ways
16:46:40 <samccann> that way ^^ or antsibull would copy them from docs/docsite/rst/examples . Then any file that does get included is there in the local docsbuild already
16:47:15 <felixfontein> it would have to not copy all files that sphinx understands
16:47:22 <felixfontein> like .rst
16:47:41 <samccann> yeah the include directive has this lovely warning
16:47:43 <samccann> The "include" directive represents a potential security hole. It can be disabled with the "file_insertion_enabled" runtime setting.
16:47:57 <samccann> sooo... .maybe we should just not do this :-)
16:48:15 <felixfontein> well we already have that problem :)
16:48:43 <samccann> true. we could turn it off with that flag
16:48:58 <felixfontein> I guess it would break parts of the docsite, since some docs depend on it
16:49:11 <samccann> yeah I know I have a few files that use the include
16:49:25 <samccann> and I think those vmware example docs make heavy use of it as well
16:49:31 <felixfontein> `grep -R '.. include::' docs/docsite/rst/` in ansible/ansible has quite a few results
16:50:44 <samccann> yeah most of those are me 'being clever'.. .but a few are not
16:50:59 <samccann> oh we have only 10 min left
16:51:05 <samccann> #topic Open Floor
16:51:14 <samccann> in case anyone has something else we should talk about today?
16:52:03 <felixfontein> I think we have a result on https://github.com/ansible-community/antsibull/pull/355#issuecomment-1062096084: left-aligned it is
16:52:08 <samccann> finishing off the examples - we either allow/extend the use of include in antsibull, or collection owners just copy their examples into docs if they want it
16:53:04 <samccann> felixfontein: what's preventing that PR merging (after the left-aligned happens)?
16:53:27 <samccann> I'd like to get this merged and a couple of collections using it. We can then demo/talk about it during the contributor summit coming up in April
16:54:01 <felixfontein> samccann: did you check with core whether they like the information shown for ansible.builtin? that's probably the biggest potential blocker
16:54:08 <briantist> I didn't know about include, it sounds useful but risky.. in general I still stand by comment in the thread, I think there's no one-size-fits-all solution for examples, because they vary so much, so it an approach where exampels could be standalone probably makes sense, and folks can put examples into documentation if thy want it in a page (whether we have an easy way to do that without copy/pasting or not)
16:54:28 <samccann> felixfontein: yes I did and didn't have anyone raise a flag.
16:54:37 <felixfontein> and once we merge this the format is more or less fixed (resp it has to stay backwards compatible), so if we want to simplify something or change something, we should do it now and not later
16:55:00 <felixfontein> samccann: that's good :)
16:55:02 <briantist> and I think a beneficial feature would be some easy way to generate a link to an example file from RST, without hardcoding, but I'm not sure if that's even possible to do precisely
16:55:51 <felixfontein> samccann: we might want to quickly look at the TOC question / secction headers question first
16:56:03 <felixfontein> i.e. https://github.com/ansible-community/antsibull/pull/355#issuecomment-1057397438
16:56:29 <samccann> #info last chance to comment on the format for  the yaml file that includes links on collection docs pages  - https://github.com/ansible-community/antsibull/pull/355
16:57:31 <samccann> ok so TOC is good
16:57:46 <samccann> I'm not sure if we need to add Authors to the TOC? I'm fine either way
16:59:29 <felixfontein> should communication be a top-level section then, like Guides and Plugin Index?
17:00:00 <samccann> sounds good to me
17:00:20 <felixfontein> ok, I'll try that
17:00:29 <samccann> cool thanks!
17:01:48 <samccann> I think we bring up the yaml file format in tomorrow's community meeting and finalize it all this week?
17:02:14 <samccann> assuming that's a workable timeline. I'm not sure what it takes to finish off the remaining bits and bobs
17:02:38 <gwmngilfen-work> +1 from me, I think it's time to get it into people's hands
17:02:55 <gwmngilfen-work> and as ever, much thanks to felixfontein for the hard work
17:03:56 <samccann> yes indeed!
17:04:45 <samccann> ok we are 4 min over.. anything else before I end the meeting?
17:05:06 <felixfontein> samccann: the community meetings do no longer vote, so if we want the SC to vote on it it will be two more weeks :)
17:05:10 <felixfontein> (fully async ;) )
17:06:15 <samccann> do you want an SC vote on the format part?
17:06:56 <samccann> We could bring up the call to vote tomorrow and give them a week to do it?  I suppose it is a specific format that all collections owners will have to follow if they opt into this
17:07:29 <felixfontein> I don't think it's needed; also we did ask for comments multiple times, and so far there hasn't been much feedback in general, so I'm not sure how much interest there actually is
17:07:42 <felixfontein> resp. how much time SC members have for this :)
17:07:54 <felixfontein> there are some other, more important votes running which do not have that much votes yet
17:08:14 <felixfontein> if you want a vote let's do a 'quick' one (i.e. on week)
17:08:16 <felixfontein> *one
17:08:16 <samccann> ok I'm happy to ship it as is
17:08:55 <samccann> or yeah, we could give it a week and bring it up tomorrow as a 'last call for feedback'
17:09:37 <felixfontein> sounds good to me
17:11:32 <samccann> ok cool
17:11:39 <samccann> that's about it for this week! thanks everyone!
17:11:42 <samccann> #endmeeting