14:31:05 <samccann> #startmeeting Docs Working Group aka DaWGs
14:31:05 <zodbot> Meeting started Tue Oct  6 14:31:05 2020 UTC.
14:31:05 <zodbot> This meeting is logged and archived in a public location.
14:31:05 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:05 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:05 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:12 <samccann> #topic opening chatter
14:31:25 <samccann> So who's around today to talk about docs fun?
14:31:45 * gundalow waves
14:31:50 <gundalow> Here for ~15 minutes
14:31:56 <samccann> #chair gundalow
14:31:56 <zodbot> Current chairs: gundalow samccann
14:32:54 <samccann> lmodemal abadger1999 cyberpear andersson007_ ? around for docs chat today?
14:33:10 <lmodemal> Hello :)
14:33:20 <samccann> woot woot!
14:33:24 <samccann> #chair lmodemal
14:33:24 <zodbot> Current chairs: gundalow lmodemal samccann
14:33:26 <cyberpear> o/
14:33:33 <samccann> #chair cyberpear
14:33:33 <zodbot> Current chairs: cyberpear gundalow lmodemal samccann
14:33:51 <samccann> #topic introductions
14:34:24 <samccann> So we have a new writer joining us today - lmodemal !! She'll be rockin the docs upstream and down for Ansible now
14:34:34 <gundalow> woot
14:34:36 <gundalow> welcome :)
14:34:38 <lmodemal> Hello everyone! Happy to be here with you all.
14:34:48 <lmodemal> thank you gundalow!
14:35:29 <samccann> #info lmodemal joining the Ansible writer team!
14:35:40 <samccann> ok the agenda  - https://github.com/ansible/community/issues/521#issuecomment-700804501
14:35:59 <samccann> gundalow - since you only have 10 min left, anything there you want us to discuss first while you are around?
14:37:04 <gundalow> #info Contributor Summit and Ansible Fest is next week Agenda is here https://etherpad.opendev.org/p/virtual-ansible-contributor-summit-october-2020
14:37:35 <samccann> woot!  Always a fun time, esp the contributor summit (but I could be biased)
14:38:00 * cyberpear still needs to officially sign up
14:38:07 <samccann> oh there is one topic I'd like to rush in before we lose gundalow
14:38:18 <samccann> #topic - removing docs rst etc from the ansible tarballs
14:38:49 <gundalow> abadger1999: for when you are around, this topic maybe of interest
14:39:02 <samccann> This came up here in irc last week. I don't recall the exact stats, but the ansible tarballs are quite large now, so we were asked to consider if we're okay with removing the docs (I think rst files)  to slim the tarballs down a bit.
14:39:46 <samccann> I frankly don't know much about it. I  think abadger1999 suggestion was to create a separate docs tarball instead, for anyone looking for that stuff
14:40:20 <samccann> and the extended thought - that we could include the HTML files as well then, and solve the 'why don't you have downloadable docs' issues that pop up regularly.
14:40:37 <samccann> gundalow - any thoughts?
14:40:45 <samccann> (and anyone else)
14:40:59 <gundalow> so is this specifically `ansible-base`?
14:41:23 <abadger1999> Morning
14:41:46 <gundalow> or also some of the supported collections from the Content Team which include manually built RST for module docs
14:41:50 <samccann> phew.  ^^^ probably remembers better. I think it was both ?
14:42:07 <gundalow> #chair abadger1999
14:42:07 <zodbot> Current chairs: abadger1999 cyberpear gundalow lmodemal samccann
14:42:10 <gundalow> Morning :)
14:42:14 <samccann> oh my. Those rst files within collections are part of the tarballs as well?
14:43:03 <samccann> #info ansible tarballs are quite big now. We're considering removing the docs rst files and making a separate tarball just for docs for those who may want it locally. could add HTML to it as well?
14:43:19 <abadger1999> It was both.
14:43:29 <abadger1999> I do not know about rst inside of collection tarballs.
14:43:45 <abadger1999> If there are, then that could be a large reason the new tarballs are so much bigger.
14:44:42 <samccann> #action - find out if .rst files within a collection are part of the collection tarballs (and thus making Ansible tarball that much bigger)
14:44:52 <abadger1999> Looks like there are some.
14:44:58 <abadger1999> Not a ton (yet), though.
14:45:02 <samccann> unfortunately its a rock vs hardplace on that one until Galaxy shows module docs
14:45:08 <abadger1999> Yeah.
14:45:31 <samccann> hmm... all 15? of the ansible-maintained collections probably have module .rst files. and yeah... growing.
14:45:36 <abadger1999> It's going to be interesting wanting to move scenario guides into the modules.....
14:45:55 <samccann> #info yes, seems like the collection tarball does include  .rst files.
14:46:04 <abadger1999> Since then we'll have both duplicated content an dadditional content in there.
14:46:29 <abadger1999> (318 rst files in collections for ansible-2.10.0)
14:46:36 <samccann> that ^^ also impacts any ideas we have of moving collection-level scenario guides into the collections themselves (and then pipelining them back like we do module docs today)
14:46:45 <cyberpear> maybe keep them w/ the individual collection tarballs, but strip them from the ansible tarball?
14:47:02 <abadger1999> Yeah..... if licensing allows us to do that.
14:48:13 <samccann> #info 318 rst files in collections for ansible 2.10.0
14:48:41 <samccann> oh and that was moving scenario guides into the /docs folder for the collection it covers (where they are for a single collection).
14:49:10 <samccann> abadger1999 - can you easily see how many rst files are in `ansible-base` ? just for comparison
14:49:11 <gundalow> Do supported collections still need the RST files now we have https://docs.ansible.com/ansible/2.10/collections/community/ ?
14:49:15 <gundalow> Got to drop, back in 15
14:50:01 <samccann> gundalow (when you get back) -yes because the team feels that they need the module docs within galaxy itself. So today, they link to all those rst files from their collection readme, which is visible in Galaxy.
14:51:14 <abadger1999> My count was off... 967 rst files in ansible-2.10.0
14:51:37 <samccann> the question is - do we think these collection-level rst files are causing enough bloat to remove them?  I could ask the team if they can replace them with links to their collection-level top page now via galaxy.yml (I think felix had that idea the other day)
14:52:07 <samccann> The sad drawback though - the collections move faster than docs.ansible.com now, so they will still be behind so to speak on the docs :-(
14:52:37 <abadger1999> 328 static rst file in ansible-base.
14:52:39 <samccann> ooch. that's a lot of .rst files.  So is there a way to just remove them all from the tarballs?
14:53:00 <felixfontein> tadeboro: sorry, got confused about the versions, in that case +1 to the patch level ;)
14:53:06 <felixfontein> hi all!
14:53:09 <cyberpear> are we getting complaints of too big tarball?
14:53:18 <samccann> #chair felixfontein
14:53:18 <zodbot> Current chairs: abadger1999 cyberpear felixfontein gundalow lmodemal samccann
14:53:21 <samccann> Welcome!
14:53:35 <cyberpear> at least for -base, I think they should stay
14:53:36 <abadger1999> The number of generated docs is  around 4694
14:54:10 <abadger1999> #undo
14:54:10 <zodbot> Removing item from minutes: INFO by samccann at 14:48:13 : 318 rst files in collections for ansible 2.10.0
14:54:29 <samccann> #info there are 328 static .rst files in `ansible-base,  967 .rst files in the Ansible 2.10.0 tarball.
14:54:53 <samccann> thanks abadger1999... I always forget the undo option
14:55:05 <abadger1999> #info 967 rst files in collections for ansible-2.10.0 ; 328 static rst files in ansible-base-2.10.0 ; estimated 4694 generated rst files
14:55:12 <samccann> kewl thanks
14:55:12 <abadger1999> #undo
14:55:12 <zodbot> Removing item from minutes: INFO by abadger1999 at 14:55:05 : 967 rst files in collections for ansible-2.10.0 ; 328 static rst files in ansible-base-2.10.0 ; estimated 4694 generated rst files
14:55:20 <samccann> HAHAH
14:55:24 <abadger1999> :-)
14:55:27 * samccann sits on hands for a moment
14:55:45 <abadger1999> Just woke up I'm writing too quick and should read faster :-)
14:56:20 <samccann> cyberpear - what are your thoughts about why we should keep them in `ansible-base`? Just for historic reasons? or you know of folks using them from there?
14:57:43 <abadger1999> Note that my idea would be that they are moved out of ansible-base but that there is another tarball (or maybe two?) like ansible-documentation.tar.gz that contains the source and built documentation.
14:58:33 <abadger1999> So people who wanted to have a sopy of the documentation locally could still download that tarball.
14:59:08 <felixfontein> IMO having docs in a separate tarball would be best - both for ansible-base and for ansible
14:59:48 <felixfontein> I don't care about whether there are two tarballs (ansible-base-docs and ansible-docs) or one (ansible-docs)
15:00:27 * gundalow returns and reads scrollback
15:00:30 <samccann> presumably the tarball gets rebuilt for every patch release? (ansible-base-2.10.3, etc )
15:01:07 <abadger1999> The intermingling of ansible and ansible-base docs are probably also a difficulty here.  If we do one tarball, then we have to figure out how to deal with there being two source tarballs with two different release schedules.  If we do two tarballs, then we have to deal with the fact that the web docs build a single unified document but we're trying to split it into two tarballs.
15:01:57 <gundalow> samccann: FYI you can keep the RST in the git repo, though exclude them from the built collection tarball
15:02:04 <abadger1999> samccann: yeah every patch release
15:02:21 <samccann> k thanks. Definitely want to keep the .rst in git where they are today
15:02:31 <felixfontein> abadger1999: that's kind of the same problem as "there's one docsite for both packages" :)
15:02:38 <abadger1999> felixfontein: yeah.
15:02:52 <samccann> yeah that's a problem 'on the horizon' to fix. in fact it's the next agenda item to discuss :-)
15:03:22 <samccann> But before we move on, we don't have enough people for a 'binding vote' but ya know... vote early, vote often!
15:04:02 <samccann> POLL -should we move .rst files out of ansible and ansible-base and create a separate ansible-docs tarball (leaving technical details for later)
15:04:26 <abadger1999> yeah... also, if we change this, we'd need to get buy in from the core team (at least) as well.
15:04:52 <abadger1999> So this is a poll of: Do we think this is a good direction to explore further?
15:05:07 <samccann> oh definitely. I just want a feel for what folks thing right now... so nonbinding vote -  +1 in favor, -1 leave em in the tarball  (and yes, is this a direction to explore)
15:05:09 <samccann> #chair
15:05:09 <zodbot> Current chairs: abadger1999 cyberpear felixfontein gundalow lmodemal samccann
15:05:34 <felixfontein> +1
15:05:37 <abadger1999> I think I'm +1.... there's definitely needs that can be addressed by this.
15:05:51 <abadger1999> and I can't think of another way to address all of them.
15:05:54 <samccann> +1
15:07:06 <lmodemal> 0
15:07:28 <cyberpear> weak -1, but as long as there's a tarball w/ the docs, it's probably fe
15:07:35 <cyberpear> *fine
15:08:17 <gundalow> Before voting it would be good to know how much space would be saved (in MB and as a %age)
15:08:37 <cyberpear> gundalow++ good to have stats
15:08:37 <samccann> Ok I think we'll say - needs more work to flesh out the idea
15:09:41 <samccann> #info let's investigate this a bit further - how much MB saved, % of the size of the existing tarballs etc.  And how useful would the folks who want downloadable docs find it as html files in the tarball
15:09:52 <gundalow> Thanks
15:10:13 <samccann> Ok gonna shift to the next topic
15:10:28 <samccann> #topic Separating `ansible-base` docs from Ansible docs
15:10:43 <abadger1999> Yay!
15:10:49 <felixfontein> ah, the tough questions :)
15:11:02 <samccann> This one is a real tangle, because there are a lot of things going on on the docsite itself (someone's redesigning it for better usability etc)
15:11:34 <samccann> but I think we can make some progress in thinking about - what does a user or developer for `ansible-base` need for docs
15:11:54 <samccann> and/or - which docs should NOT be versioned anyway (possibly a side topic but feels related)
15:12:46 <samccann> and lastly - what do we absolutely HAVE to have in place before Ansible 2.11 (that I think is tentatively coming in Jan/Feb?
15:12:59 <felixfontein> should ansible-base get its own docsite, (kind of) independent of the ansible docsite?
15:13:15 <samccann> that's part of it, yes.
15:13:33 <abadger1999> #info design choices to make: what docs does a user vs developer of ansible-base need?
15:13:36 <samccann> So like Tower is separate on docs.ansible.com,  ansible-base could be separate
15:13:45 <samccann> thanks abadger1999 :-)
15:13:51 <abadger1999> #info design choices: what docs should NOT be versioned?
15:15:04 <abadger1999> #info redesigns still have to work within the Ansible-2.11  deadline for something presentable  (late Jan/early Feb)
15:15:41 <samccann> #info the Ansible 2.11 deadline is because the url has a version number - so ansible-base would still be 2.10 in the url, but Ansible would be 2.11 for example
15:16:36 <gundalow> I wonder if some sort of table of personas, products&tools and versions would help us understand how things could be split up
15:16:46 <samccann> how about we start with a basic what's the impact of 'moving' say some developer docs to a new url?  Those are the ones we're thinking might be 'no version' aka like /devel/ only
15:17:03 <abadger1999> samccann: Is the idea still that ansible-base docs would be developer-focused and the ansible docs would be end-user focused?  Or was that too simplistic so it's going to be more of a mixture?
15:17:04 <samccann> #info some sort of table of personas, products&tools and versions would help us understand how things could be split up
15:17:08 <samccann> cuz that's a great idea
15:17:45 <cyberpear> the only benefit of incrementing to 2.11 is so we can make deprecations?
15:17:49 <samccann> abadger1999 - I get some conflicting messages about that one. In my mind, yes, the majority user/consumer of ansible-base are developers (or collection developers)
15:17:55 <gundalow> For example "How to raise bugs;use email lists;find a meetup" isn't related to the version of anything, nor is it about a specific tool or platform
15:18:49 <gundalow> "I want to extend ansible-base to do X" is related to ansible-base and specific versions of it
15:18:55 <felixfontein> docs on how variable handling, variable precendence, ... works probably also belong to ansible-base, but are not developer oriented
15:19:07 <gundalow> Yup
15:19:25 <abadger1999> cyberpear: deprecations, removals, other backwards incompatible changes.... It's really a matter of the collections we contain wanting to move forward and we want to be sure the ansible version number warns users that the collections may not all be backwards compatible.
15:19:33 <gundalow> "As a user of ansible-base I want to know how to X" needs to be versioned along side ansible-base
15:19:37 <samccann> cyberpear: I think that's part of it, yes. But in general, with ansible-base at a slower relative pace than Ansible (in theory) - we can't continue to assume they will have the same version numbers
15:20:25 <felixfontein> maybe the Ansible docsite needs to be (mostly) a superset of the ansible-base docsite
15:20:37 <samccann> gundalow - what 'is' a user of ansible-base?  I mean beyond a general Ansible user (how to use playbooks, inventory, etc)
15:20:55 <gundalow> samccann: I'm trying to avoid using the term "ansible" :P
15:21:01 <felixfontein> could also be a collection/plugin/module developer
15:21:16 <samccann> but a developer needs the ansible-base developer guide
15:21:24 <samccann> a user needs??
15:21:29 <gundalow> concet
15:21:41 <gundalow> concepts, user guide and reference materials
15:22:11 <felixfontein> and docs of builtin modules/plugins
15:22:11 <samccann> What I'm wondering - if we have the user guides over on Ansible, can we just point ansible-base uers to that, or do we see something separate/different for an ansible-base user (for those concepts, etc)
15:23:14 <gundalow> samccann: could you expand on `over on Ansible`?
15:24:05 <samccann> Okay so an Ansible (the package) user needs all the user guides, for playbook, inventory, etc.  And all the collection module pages. That to me is the Ansible user docs so to speak
15:24:18 <felixfontein> samccann: I guess only the ansible -> ansible-base links work properly, since ansible-base might have a new release that's not contained in ansible for some months (or longer)
15:24:45 <samccann> ah good point.
15:24:52 <abadger1999> <nod>
15:25:36 <samccann> So if ansible-base adds some new feature to how inventories work... that is available only to `ansible-base` users and not Ansible users until Ansible releases with it (like 2.10 ansible-base came out first a few months back)
15:25:58 <samccann> this.is.not.easy
15:26:02 <gundalow> hehe
15:26:16 <gundalow> I guess it depends if you think `ansible` is a thing in it's own right
15:26:16 <samccann> #info  if ansible-base adds some new feature to how inventories work... that is available only to `ansible-base` users and not Ansible users until Ansible releases with it (like 2.10 ansible-base came out first a few months back)
15:27:05 <samccann> It is in a sense, because it has a specific ansible-base version included. So someone looking at /latest/ docs might find that ansible-base feature that isn't in Ansible yet
15:27:30 <gundalow> bad analogy time
15:27:30 <gundalow> Ansible Automation Platform is MS Office. It has a number of independent bits of software that you get together (word, excell, powerpoint) ansible-base, AH, ...
15:28:01 <gundalow> The MS Office documentation is mostly a top-level link to the relevant individual product docs
15:29:43 <gundalow> Likewise, in my mind I don't view `ansible` as a first class citizan, more metadata about thing:version that's included
15:29:56 <gundalow> not sure if that helps anyone here, just how I view it
15:30:04 <samccann> It does.
15:30:22 <samccann> #info as an analogy - Ansible Automation Platform is MS Office. It has a number of independent bits of software that you get together (word, excell, powerpoint) ansible-base, AH, ...
15:30:51 <samccann> #info The MS Office documentation is mostly a top-level link to the relevant individual product docs. Likewise, don't view `ansible` as a first class citizan, more metadata about thing:version that's included
15:30:56 <samccann> just so I don't lose that thought
15:30:59 <cyberpear> "ansible" is the canonical distribution of ansible-base plus content; ansible-base is like the Linux kernel; you could probably have a newer ansible-base with a given ansible version
15:32:11 <samccann> hmm... that helps as well
15:32:11 <felixfontein> "ansible" could be seen as a Linux distribution; you take a kernel version, and versions of various programs (collections), and end up with a "Ansible distribution"
15:32:52 <felixfontein> similar to Linux, everyone can create their own "Ansible distribution", though most will stick to well-known ones, or more precisely to the canoncial one: Ansible
15:33:04 <felixfontein> cyberpear: it's a good analogy!
15:34:43 <samccann> the thing I struggle with - when I think about RHEL  for example - it updates the linux kernel regularly... I'll need to check if they include any kernel-level info in their docs or just point back to linux kernel docs
15:35:30 <felixfontein> usually the user doesn't need to look at kernel docs, so w.r.t. it's a bad analogy :)
15:35:37 <jtanner> they don't rebase a major kernel revision within the lifecycle of a major version of rhel
15:35:38 <samccann> but helpful analogies for sure. We are a bit past the hour. Do folks have time to hop over to a batch of PRs felixfontein mentioned in the wee hrs this am? (about plugin index pages, and collection versions etc)
15:36:19 <samccann> #chair jtanner
15:36:19 <zodbot> Current chairs: abadger1999 cyberpear felixfontein gundalow jtanner lmodemal samccann
15:36:31 <samccann> cuz if ya talk, ya get furniture :-)  and welcome!
15:37:22 <jtanner> rhel8 for example will have 4.18.z forever, and the z will increment as time goes on
15:37:57 <abadger1999> One difference with linux distros.... we're not changing the contents that make up ansible.
15:38:22 <jtanner> https://en.wikipedia.org/wiki/Red_Hat_Enterprise_Linux#Kernel_backporting
15:38:47 <abadger1999> (rhel8 will stick to 4.18.z forever but it will also apply their own patches to that to fix important bugs.  We aren't doing that to ansible-base or the collections for the ansible package)
15:38:58 <samccann> :-)
15:39:09 <felixfontein> no analogy is perfect :)
15:39:51 <felixfontein> samccann: I have time now, no idea if anyone else has though
15:40:11 <gundalow> samccann: I'm wondering if defining the personas, products/tools  would be the next step in an Etherpad
15:40:12 <samccann> ok gonna try moving to one final topic
15:40:29 <gundalow> which we can do outside of this meeting
15:40:34 <gundalow> +1 to next topic
15:40:39 <samccann> yeah I like that idea
15:40:53 <samccann> #topic generating all module index etc
15:40:56 <samccann> plugin indexes https://github.com/ansible-community/antsibull/pull/196 - see https://ansible.fontein.de/collections/index_module.html https://ansible.fontein.de/collections/index_lookup.html https://ansible.fontein.de/collections/index_vars.html
15:41:36 <samccann> basically, users miss that all-module index... not the least because our search is less than ideal. That PR provides index pages for each plugin type
15:41:55 <gundalow> So this gives us Ctrl+F back :)
15:42:03 <samccann> I'd like to run it against 2.10 to see how big the page gets, but otherwise love the idea
15:42:08 <samccann> gundalow - yep!
15:42:34 <gundalow> sweet
15:42:56 <gundalow> I don't know what the total number of plugins in `ansible 2.10` is, apart from more than 2.9
15:43:10 <felixfontein> for non-module plugins it will not be too big, but for modules it will be a massive page. though not that much worse than the full module list for 2.9 I think
15:43:22 <samccann> #info plugin indexes https://github.com/ansible-community/antsibull/pull/196 - see https://ansible.fontein.de/collections/index_module.html https://ansible.fontein.de/collections/index_lookup.html https://ansible.fontein.de/collections/index_vars.html
15:43:26 <felixfontein> (the file size will be bigger though, since the FQCNs count for something)
15:43:58 <samccann> yeah and may keep growing if we continue including new collections in Ansible itself.
15:44:24 <felixfontein> gundalow: I've never counted, but I guess it shouldn't be a lot more... maybe 10-30% more, but I guess not 50% more or even more
15:44:34 <samccann> I'm +1 anyway as users are ...using this page for 2.9 more than I thought
15:44:56 <samccann> see https://github.com/ansible/community/issues/521#issuecomment-700914821 for the stats
15:45:44 <samccann> basically over 100K unique visits, nearly 500K visits in the past year.
15:45:45 <abadger1999> (tangent: The new inline comments codecov is doing kind of annoy me :-/  felix, I think I'll look into turning those off for the future)
15:45:52 <samccann> (just to the all module index page)
15:46:04 <samccann> abadger1999 glad I wasn't the only one!
15:46:28 <felixfontein> abadger1999: true, I've noticed that too
15:47:19 <samccann> okay so put your comments/approvals on that PR please.
15:47:41 <samccann> gonna sneak in one more
15:47:45 <samccann> #info - collection version https://github.com/ansible-community/antsibull/pull/200 - see https://ansible.fontein.de/collections/community/crypto/index.html#plugins-in-community-crypto and https://ansible.fontein.de/collections/community/crypto/acme_account_module.html#ansible-collections-community-crypto-acme-account-module
15:48:07 <samccann> That adds collection version number to the collection page and individual collection module pages.
15:48:34 <samccann> I'm +1 on that one for sure. Anyone else have thoughts on it?
15:49:36 <felixfontein> I think several people requested the version numbers
15:49:48 <samccann> oh yeah it's a definite need
15:50:53 <samccann> ok so again, please put comments/approvals on both prs so we can move ahead with them. Will be great additions to the docs and stuff peeps are looking for
15:50:57 <samccann> #topic OpenFloor
15:51:22 <samccann> For any patient folks still hanging around - now's the time to bring up any other docs ideas/prs/questions/ etc
15:53:03 <gundalow> Nothing else from me
15:54:00 <samccann> ok gonna close this down. Thanks everyone!
15:54:03 <samccann> #endmeeting