documentation_working_group_aka_dawgs_supplemental
LOGS
15:31:34 <samccann> #startmeeting Documentation Working Group aka DaWGs Supplemental
15:31:34 <zodbot> Meeting started Thu Dec 17 15:31:34 2020 UTC.
15:31:34 <zodbot> This meeting is logged and archived in a public location.
15:31:34 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:31:34 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:31:34 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs_supplemental'
15:31:44 <samccann> #topic opening chatter
15:31:44 <lmodemal> \o/
15:31:53 <samccann> #chair lmodemal
15:31:53 <zodbot> Current chairs: lmodemal samccann
15:32:00 <samccann> who else is around to talk docs?
15:32:09 <acozine> o/
15:32:36 <felixfontein> lurking :)
15:32:38 <samccann> #chair acozine
15:32:38 <zodbot> Current chairs: acozine lmodemal samccann
15:32:44 <samccann> #chair felixfontein
15:32:44 <zodbot> Current chairs: acozine felixfontein lmodemal samccann
15:33:04 <samccann> lurking counts today :-)  We have tough competition on the community channel so might be a short one
15:33:41 <samccann> do we ping the badger? let him sleep in??
15:34:23 <felixfontein> :)
15:35:09 <samccann> Well, let's get started   agenda - https://github.com/ansible/community/issues/521#issuecomment-742807992
15:35:20 <samccann> #info mockups ...sort of
15:35:26 <samccann> #undo
15:35:26 <zodbot> Removing item from minutes: INFO by samccann at 15:35:20 : mockups ...sort of
15:35:34 <samccann> #topic mockups ...sort of
15:35:38 <acozine> heh
15:35:59 <samccann> #info this is a rough mockup of what Ansible 3.x would look like - http://docs.testing.ansible.com/ansible/3.x/index.html
15:36:20 <samccann> #info this is a rough mockup of what Ansible core would look like - http://docs.testing.ansible.com/ansible/2.11/index.html
15:37:23 <samccann> they are by no means perfect, but just to give you the idea of what is on each of them. TL;DR: Ansible 3.x is complete, Ansible-core is just the user and developer guides and built-in modules
15:39:11 <acozine> this is a good step forward; it does illustrate the concerns we'd all voiced in past meetings about linking from one site to the other and how would a user know if/when she switched sites
15:39:34 <acozine> I think we can manage those things
15:39:46 <acozine> and this is the best way forward we've found so far
15:39:56 <felixfontein> btw, why `3.x` in the url and not just `3`?
15:40:05 <felixfontein> in any case, looks great! :)
15:40:11 <samccann> cuz its the only way I could get it to publish ?
15:40:14 <samccann> :-)
15:40:33 <acozine> because the pipeline only accepts `*.*` in the version slot
15:40:41 <samccann> `3` wouldn't publish in the jenkins job.  It may not remain 3.x..just need someone smarter to figure out what's wrong
15:40:59 <felixfontein> ok :)
15:41:03 <acozine> we couldn't tell exactly where that constraint is introduced
15:41:29 <samccann> #info the mockup uses 3.x in the url for test purposes as the pipeline currently requires x.y in the version slot
15:42:09 <samccann> So the Ansible 3.x has a proposed banner to say what it is and how to find core.  I forgot to update the core docs with a similar banner
15:43:41 <samccann> should we move on and see if we can brainstorm abit about unversioned docs? (aka community and maybe developer guides?)
15:43:56 <acozine> sure
15:44:09 <samccann> #topic unversioned docs
15:44:39 <samccann> #info can we publish just one release-independent version of the community guide? the developer guide? anything else?
15:44:59 <samccann> so let's start with a list - what do we think doesn't need to have a version attached to it
15:45:33 <acozine> community and developer guides both deal only with things as they are today, so they can definitely be unversioned
15:46:26 <samccann> is there a part of the develper guide that has to be pulled out tho? for say someone wanting to fix something in stable-2.9?
15:46:36 <acozine> nobody needs to know what the requirements for modules were in version 2.5 or when a working group was introduced
15:46:39 <samccann> I think bugfixes are my only worry...
15:46:46 <samccann> heh
15:46:54 <acozine> but bugfixes should always go into devel first
15:46:57 <acozine> then get backported
15:47:38 <acozine> so if you find a bug in 2.9, you follow the same procedure as if you found it in (proto-)2.11
15:47:52 <samccann> ok so the followon question - do we have the TIME to create some kind of third docsite/area for the unversioned stuff?
15:48:10 <acozine> I think that's why we haven't done it in the past
15:48:13 <samccann> so docs.ansible.com/contributors - and have community and dev guides there?
15:48:47 <acozine> I think heading toward unversioned content is probably part of a much longer-term roadmap
15:49:10 <samccann> #info - do we have the time to create something like  docs.ansible.com/contributors - and have community and dev guides there? in time for the Feb Ansible 3.0.0 release
15:49:25 <samccann> agreed, but at least the community guide is 'low hanging fruit'
15:49:41 <acozine> also, the more top-level sites we have, the more switching back and forth users have to do
15:49:53 <samccann> yeah
15:50:54 <samccann> so I know the dev guide gets a LOT less traffic than user guides/modules etc
15:50:54 <acozine> I remember getting some feedback at one point about "why doesn't Ansible have a developer site, like dev-docs.ansible.com, so developers don't have to wade through all that user content?"
15:51:37 <samccann> so the only benefit I can think of right now to trying for  developer/contributor docsite is that we wouldn't repeat that info on the other two docsites
15:52:00 <samccann> otherwise, both are duplicated between core and Ansible
15:52:05 <acozine> true
15:52:21 <samccann> but on the flip side -what we are doing is an 'interim fix' until that longterm plans get.. well... planned :-)
15:52:36 <acozine> yep
15:52:52 <acozine> nothing is permanent, but this is especially not
15:53:02 <acozine> Docs Ephemera
15:53:06 <samccann> so i could go either way on this.  I 'think' once we figure out how to split things for Ansible vs core, it would be 'relatively easy' to split it a third way to create release independent
15:53:13 <samccann> the zen of documentation
15:54:39 <acozine> the community docs probably fit best in a repo in ansible-collections
15:54:54 <acozine> but we don't want to pull the developer docs out of the main repo
15:54:58 <samccann> yes and no. Core has a community
15:55:37 <samccann> I'm hoping we can/will keep those communities in sync w/ the same guides
15:56:07 <samccann> but for example, if we did docs.ansible.com/contributing - the url suggests it covers awx, ansible lint, etc etc
15:56:36 <samccann> which maybe is something we DO want, but takes longer to get it all in place
15:56:52 * samccann convincing herself NOT to create unversioned docs just yet
15:56:56 <acozine> heh
15:57:11 <felixfontein> docs.ansible.com/ansible/contributing ?
15:57:23 <acozine> felixfontein: that's pretty much where it is now
15:57:29 <acozine> except with a version number
15:57:47 <acozine> I don't know if we can mix in versioned and unversioned docs in that same URL structure
15:57:55 <samccann> yeah see I don't want to take that step, because we do have the opportunity to potentially have one overarching contributor section and put in guides for core, for collections, for xxx ?
15:58:59 <samccann> as in - it might be too early to head down that road until the docs longterm plans are more in place
15:59:19 <felixfontein> acozine: that's what I mean, just leave away the version number :) whether it's possible to mix that depends on what actually depends on that...
15:59:28 <samccann> i could of course be convinced otherwise... not the docs hill i'm dyin on today ;-)
15:59:32 <acozine> heh
16:00:29 <acozine> we could have "all versions link to the contributor guide that has no version" within the existing structure, but then how do we get users back to the version they came from?
16:01:15 <felixfontein> do we need to get users back to the version they came from? when they are on the general contributing site?
16:02:23 <acozine> maybe not
16:02:55 <acozine> if they were looking for contributor docs, then they won't want to see a particular version
16:04:19 <acozine> if they are using Ansible 2.9 and clicked on the Community section, then they want to learn more about running playbooks, though, they will want 2.9 again
16:04:56 * acozine should probably look at the existing traffic stats, to see where people go when they leave the community guide
16:06:01 <felixfontein> I would assume that people would use their browser's back button, since they don't directly see the stuff they are interested in
16:06:12 <acozine> if most users who read community pages end their visits there, that tells us that we don't need to worry about getting them to versioned docs from there
16:06:38 <acozine> yeah, they can use the back button
16:07:48 <acozine> and if we limit the TOC on the community pages, so users can't select Module/Collection Index from there . . .
16:09:40 <acozine> but I agree with samccann that February is too early for that move
16:10:41 <acozine> also, I have a raging headache, which is making me grumpy
16:10:50 <acozine> or maybe being grumpy is giving me the headache? hard to say
16:12:59 * acozine falls back on the agenda
16:13:42 <acozine> let's see, we talked about versioned/unversioned
16:14:09 <acozine> and we talked about the status of the current proposal, which is "take a look on the testing site and see if it makes sense"
16:14:51 <acozine> there's also "update on moving scenario guides to another repo"
16:15:03 <acozine> #topic can we move scenario guides to a different repo?
16:15:57 <felixfontein> I think the idea was to move the scenario guides to the collection repos, and have some mechanism in antsibull-docs to allow collections to provide RST files that are included in the doc site
16:16:08 <acozine> yes
16:16:20 <acozine> and I think it's a good idea, if we can make it work
16:17:59 <acozine> but probably not going to happen before the New Year
16:21:17 <acozine> maybe we can set up an agenda for the first week of the New Year, and come to all these topics then with fresh eyes/minds
16:22:07 <acozine> and then we can join the PR day and try to make some progress there
16:22:57 <acozine> #action acozine to create an agenda for the first week of January
16:24:03 <acozine> thanks felixfontein lmodemal samccann
16:24:09 <acozine> #endmeeting