14:31:16 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:16 <zodbot> Meeting started Tue Jul 28 14:31:16 2020 UTC.
14:31:16 <zodbot> This meeting is logged and archived in a public location.
14:31:16 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:16 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:16 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:26 <acozine> #topic opening chatter
14:31:27 <andersson007_> acozine: thanks!
14:31:37 <acozine> who's around?
14:31:41 <samccann> o/
14:32:28 <felixfontein> hey!
14:32:39 <acozine> hello, hello!
14:32:43 <acozine> #chair samccann felixfontein
14:32:43 <zodbot> Current chairs: acozine felixfontein samccann
14:33:53 <acozine> anybody else? baptistemm briantist cyberpear geerlingguy Jmainguy ?
14:34:11 * geerlingguy looks around suspiciously
14:34:42 <acozine> geerlingguy: what do you suspect?
14:34:48 <acozine> #chair geerlingguy
14:34:48 <zodbot> Current chairs: acozine felixfontein geerlingguy samccann
14:35:06 * tadeboro and his broken english are still lurking around
14:35:14 <acozine> welcome tadeboro
14:35:20 <samccann> heh
14:35:22 <acozine> I need to step away for a few
14:35:28 <samccann> #chair tadeboro
14:35:28 <zodbot> Current chairs: acozine felixfontein geerlingguy samccann tadeboro
14:35:31 <acozine> family thing (dad in hospital)
14:35:37 <samccann> no worries
14:35:59 <geerlingguy> acozine: I suspect this meeting will be amazing!
14:36:11 <samccann> heh it always is!
14:36:29 <samccann> meanwhile we had a topic request right before the meeting started, so let's get going on that one
14:36:42 <andersson007_> i took a quick look at the agenda: to have examples before parameter lists sounds interesting
14:36:44 <samccann> #topic standardize boolean value for module docs examples
14:36:54 <samccann> #link https://github.com/ansible/community/issues/521#issuecomment-656833594
14:36:56 <andersson007_> cool:)
14:37:04 <baptistemm> hello
14:37:06 <samccann> I feel like we talked about this one a couple of weeks ago?
14:37:10 <felixfontein> we did
14:37:11 <samccann> hi baptistemm !
14:37:16 <samccann> #chair baptistemm
14:37:16 <zodbot> Current chairs: acozine baptistemm felixfontein geerlingguy samccann tadeboro
14:37:32 <felixfontein> https://github.com/ansible/community/issues/521#issuecomment-656690621
14:37:43 <felixfontein> lol
14:37:50 <felixfontein> which is the link samccann already pasted....
14:38:18 <samccann> heh
14:38:53 <samccann> so the gist of it is - pick one and make all our module doc outputs use it. (docs, AH, ansible-doc)
14:39:08 <samccann> we got that far, but we didn't open issues to nudge that along.
14:39:19 <felixfontein> adjusting ansible-doc is harder since it only does absolutely minimal post-processing
14:39:42 <felixfontein> IIRC we wanted to ask more involved stakeholders
14:39:51 <felixfontein> like core team, galaxy/AH team, ...
14:40:07 <felixfontein> (or maybe it was just me who suggested that)
14:40:33 <samccann> no, we have an action item listed to create a proposal to standardize. We just haven't done it yet :-P
14:40:45 <andersson007_> maybe a dumb question, what does AH mean?:)
14:40:48 <felixfontein> yep, I just found it in the logs as well...
14:40:49 <samccann> meeting minutes are fantastic!  Following up on them?  less so
14:41:06 <felixfontein> andersson007_: Automation Hub, the non-free version of galaxy which you get if you throw money at redhat ;)
14:41:09 <samccann> AH is Automation Hub.  The red-had downstream version of Galaxy, sortof
14:41:15 <samccann> AAHAHAH
14:41:22 <andersson007_> felixfontein: ah, got it, thanks
14:41:56 <samccann> #action samccann to followup w/ acozine on the standardizing of boolean output across ansible docs outputs
14:42:27 <samccann> anything else to discuss on that one? other than get off our duffs and start the discussion w/ wider audience?
14:43:17 <felixfontein> don't think so
14:43:22 <tadeboro> I would just add that I tend to suggest people to use true/false since they work the same way in YAML 1.1 and YAML 1.2
14:43:42 <tadeboro> yes and no are strings in YAML 1.2.
14:43:49 <felixfontein> tadeboro: I think someone already mentioned that last time, and that should definitely go into the proposal as well
14:44:42 <samccann> #info yaml 1.1 and 1.2 use true/false the same way... yes/no are strings in yaml1.2  - thus true/false might be the better standard to use
14:45:12 <samccann> ok switching to the next topic
14:45:26 <samccann> #topic should examples show up before the module options section?
14:46:03 <samccann> This came up recently that some users of the docs are having to scroll scroll scroll down to the example section as the more common area of module docs they want to look at
14:46:14 <felixfontein> when using the docs as a reference, params are more important
14:46:20 <samccann> Do others see this as a preference? that examples are more frequently used than params?
14:46:30 * acozine is back at the keyboard
14:46:38 <samccann> welcome back
14:46:43 <baptistemm> for me I prefer to have explanation how a module works rahter than examples that people will copy paste.
14:46:45 <felixfontein> also, there's no need to scroll if you can click at the correct place in the TOC :D
14:46:55 <acozine> as a user, I generally read the params first, then looked at the examples later
14:46:58 <samccann> yeah was thinking that as well felixfontein
14:47:03 <acozine> yep, me too
14:47:38 <felixfontein> IMO synopsis should always be at the top
14:47:52 <samccann> tadeboro - thoughts?
14:47:57 <felixfontein> (what comes after that is debatable)
14:48:13 <tadeboro> Most people I have the pleasure of working with, tend to use ansible only a few times a month. And the way most of them uses the docs in this situation is search for module docs, copy the most relevant example, and then modify it as needed.
14:48:48 <geerlingguy> There's already a TOC at the top, and I like the order the way it is (IMO)... sometimes I need to look at examples, sometimes at the parameters
14:48:51 <samccann> that ^^ is how I use a lot of things I'm not familiar with - find the closest example and hack from there
14:49:12 <tadeboro> And even people that use ansible often tend to use examples as a quick refresher on how a module should be used.
14:49:13 <samccann> baptistemm - thoughts?
14:49:14 <geerlingguy> ^ I do that too, but I feel like examples after the 'formal' stuff makes more sense logically
14:49:34 <geerlingguy> when I build README docs in my projects I always put the examples at the end, too
14:49:44 <samccann> I'm trying to dig out the ansible users here to see what they do. I think we tend to be developer-heavy in this meeting
14:50:17 <felixfontein> maybe ask in #ansible?
14:50:33 <samccann> and fwiw even tho I deal with these pages every day, I frequently forget to use the TOC to jump down to the section I'm interested in :-)
14:50:36 <felixfontein> the developer-user ratio there might be better (I don't know, haven't been there for quite some time)
14:50:43 <tadeboro> When I look at the README files in the git repo, I almost expect a TL;DR section that tells me how to get up and running in a minute or so.
14:50:51 <baptistemm> depends how you see the purpose of documentation, puppet resource documentation has no example https://puppet.com/docs/puppet/6.16/types/service.html and
14:50:58 <acozine> I doubt there's an order for long module docs pages that will make everyone happy
14:51:08 <baptistemm> I think they are clear :)
14:51:27 <tadeboro> And this is what I miss in the ansible docs: a short example or two at the top that showcases the common use case or two.
14:52:17 <felixfontein> I'm not sure that works for all modules
14:52:33 <samccann> should we take this further/wider? create a poll somewhere and ask users to vote on which sections they use the most?
14:52:37 <tadeboro> If anyone is interested in how reverse order looks like, here is an example: https://sensu.github.io/sensu-go-ansible/modules/asset.html
14:52:42 <felixfontein> sometimes there are no "short" examples (at least none that help users who don't already know the module by heart)
14:53:20 <samccann> yeah I'm not sure every module has examples. I know every plugin does not, and we expose them all now in the docs pages
14:53:27 <acozine> it would be easy(ish) for very focused modules but hard for modules that can fulfill a lot of different use cases
14:53:39 <samccann> and the network examples are now longer than the parameters for their resource modules for sure
14:54:10 <tadeboro> The Sensu users seem to enjoy this layout, but they tend to be ansible newcommers.
14:54:15 <felixfontein> maybe we need a new optional section `SHORT_EXAMPLE` :)
14:55:24 <tadeboro> felixfontein: This is almost exactly what we planned initially, but then our examples turned out to be short-enough end we stopped working on that.
14:55:25 <acozine> tadeboro: it's an approach that matches well with modules like the Sensu ones, where users generally have very similar use cases because the tool does a very well-defined job
14:55:47 <acozine> that's a nice-looking page
14:55:57 <tadeboro> Our idea was to add a maginc comment to the samples that should be showcased at the top.
14:56:29 <felixfontein> that doesn't work in general since EXAMPLES can be random text
14:56:50 <felixfontein> (unfortunately)
14:57:06 <samccann> #info example of a module docs page with examples at the top - https://sensu.github.io/sensu-go-ansible/modules/asset.html
14:57:16 <tadeboro> felixfontein: We were about to ho with something like #: START ... #: END
14:57:57 <tadeboro> Another thing I noticed is: since we have our examples at the top of the page, no one cares that our parameters section is all over the place stylistically ;)
14:59:46 <acozine> heh
15:01:46 <samccann> #info example of a module with a long parameters section and a long examples section - https://docs.ansible.com/ansible/2.10/collections/cisco/iosxr/iosxr_acls_module.html#ansible-collections-cisco-iosxr-iosxr-acls-module
15:01:55 <tadeboro> But all that being said, I agree that having examples such as https://docs.ansible.com/ansible/2.10/collections/fortinet/fortios/fortios_user_group_module.html#examples at the top is not ideal.
15:02:11 <samccann> Ok so we can't solve it all here in this meeting.  So it's POLL TIME!
15:02:39 <baptistemm> should we wait for a IRC command?
15:02:41 <samccann> POLL - Extend this discussion of where examples should be on a module docs page to more users to find their preferences
15:02:43 <baptistemm> ah
15:02:54 <samccann> (+1 means yes, -1 means don't bother/end of discussion)
15:02:59 <baptistemm> -1
15:03:19 <samccann> #chair
15:03:19 <zodbot> Current chairs: acozine baptistemm felixfontein geerlingguy samccann tadeboro
15:03:46 * baptistemm is looking how the ansible docs look like on automation platform
15:04:00 <felixfontein> -1 (as it's not that simple, and we have too many other things as well)
15:04:35 <baptistemm> also people won't bother looking to important stuff like requirement
15:05:05 <tadeboro> -1 (I did not even notice that my remark was made into an agenda item until five minutes ago)
15:05:15 <baptistemm> +I'm afraid of
15:05:49 <samccann> hahah!  sorry tadeboro to pounce that one on you, but it seemed worth discussing anyway
15:05:52 <tadeboro> Although we will keep placing the examples at the start for our collections ;)
15:06:08 <samccann> -1
15:06:30 <samccann> ok gonna close the poll.
15:06:44 <samccann> #info for now, we will keep examples where they are.
15:06:58 <samccann> #topic Porting guide/changelog updates
15:07:12 <samccann> anything new/interesting in that neck o the woods felixfontein ?
15:07:29 <felixfontein> the ansible changelog now has a new home: https://github.com/ansible-community/ansible-build-data/blob/main/2.10/CHANGELOG-v2.10.rst
15:07:34 <felixfontein> (new = first ;) )
15:07:55 <samccann> #info ansible changelog now has a new home: https://github.com/ansible-community/ansible-build-data/blob/main/2.10/CHANGELOG-v2.10.rst
15:08:24 <samccann> good times!
15:08:27 <felixfontein> also I started a PR to move the remaining non-base things from the ansible-base porting guide into the ansible changelog and porting guide: https://github.com/ansible-community/ansible-build-data/pull/22 with one of two PRs in antsibull
15:09:04 <felixfontein> and then there's a PR to rename the ansible-base porting guide to porting_guide_base_2.10.rst, and add an automatically generated ansible 2.10 porting guide: https://github.com/ansible/ansible/pull/70891
15:09:41 <samccann> #info PR to move the remaining non-base things from the ansible-base porting guide into the ansible changelog and porting guide: https://github.com/ansible-community/ansible-build-data/pull/22 with one of two PRs in antsibull
15:09:51 <samccann> #info PR to rename the ansible-base porting guide to porting_guide_base_2.10.rst, and add an automatically generated ansible 2.10 porting guide: https://github.com/ansible/ansible/pull/70891
15:10:07 <felixfontein> the PR diff shows the manual data extracted from the porting guide: https://github.com/ansible-community/ansible-build-data/pull/22/files
15:10:35 <samccann> #info he PR diff shows the manual data extracted from the porting guide: https://github.com/ansible-community/ansible-build-data/pull/22/files
15:10:44 * samccann trolls felixfontein w infos
15:10:54 <felixfontein> :)
15:11:39 <felixfontein> also, a bit unrelated, Ansible 2.10.0a6 has been released yesterday
15:11:47 <felixfontein> I think abadger1999 didn't got around to announce it yet
15:11:50 <samccann> yep
15:11:57 <baptistemm> 2 releases a day
15:12:01 <abadger1999> Yeah, I suck at announcements.
15:12:11 <felixfontein> baptistemm: the first one was a bit broken
15:12:30 <abadger1999> /me finds his template for that.
15:12:38 <samccann> #info Ansible 2.10.0.a6 released yesterday.  matching docs at https://docs.ansible.com/ansible/2.10/index.html
15:12:40 <felixfontein> abadger1999: you can update the template to mention the changelog ;
15:12:41 <felixfontein> )
15:12:55 <samccann> before we shift to the docs pipeline and alpha
15:13:01 <baptistemm> felixfontein: sorry perhaps you already answered elsewhere, should'nt be more usefull to show what has changed first than what that did not  ?
15:13:24 <felixfontein> baptistemm: gundalow asked for that yesterday too, and I created an isuse, but didn't worked on it yet
15:13:33 <baptistemm> felixfontein: ok
15:13:38 <samccann> felixfontein - so in summary you created the base porting guide,  and moved the cruft that didn't belong there to either the ansible porting guide or the ansible changelog, yes?
15:13:40 <felixfontein> https://github.com/ansible-community/antsibull/issues/161
15:13:48 <baptistemm> thanks
15:14:15 <felixfontein> samccann: I moved the things to the ansible changelog, to the sections that will end up in the porting guide - so in the end it will be in both changelog and porting guide
15:14:31 <samccann> #info request to move unchanged sections to the en d - https://github.com/ansible-community/antsibull/issues/161
15:14:35 <felixfontein> (and if the collection manage to include these things into their own changelogs before 2.10.0 is released, we can kick it out the generic part)
15:14:46 <samccann> kewl thanks
15:14:51 <felixfontein> if you have other suggestions etc. for the changelog, please tell me :)
15:15:18 <samccann> #action - all - review the changelogs for any further feedback
15:15:42 <samccann> anything else before we charge ahead to the docs pipeline?
15:16:11 <felixfontein> ah, one thing
15:16:44 <felixfontein> so I guess that once the auto-generated changelog is in place, we have to do the following steps after every release: 1) generate the latest porting guide, 2) merge it into devel, 3) backport it to stable-2.10, 4) rebuild docs
15:17:29 <felixfontein> is that correct?
15:17:49 <samccann> off the top of my head it seems correct
15:18:05 <samccann> #info once the auto-generated changelog is in place, we have to do the following steps after every release: 1) generate the latest porting guide, 2) merge it into devel, 3) backport it to stable-2.10, 4) rebuild docs
15:18:09 <felixfontein> I guess this will only change once the ansible docs are separated from the ansible-base docs
15:18:19 <felixfontein> #undo
15:18:20 <zodbot> Removing item from minutes: INFO by samccann at 15:18:05 : once the auto-generated changelog is in place, we have to do the following steps after every release: 1) generate the latest porting guide, 2) merge it into devel, 3) backport it to stable-2.10, 4) rebuild docs
15:18:28 <felixfontein> #info once the auto-generated porting guide is in place, we have to do the following steps after every release: 1) generate the latest porting guide, 2) merge it into devel, 3) backport it to stable-2.10, 4) rebuild docs
15:18:37 <felixfontein> sorry, should have been "porting guide", not "changelog" :)
15:18:43 <samccann> doh yeah. heh
15:19:00 <felixfontein> (I start confusing these two...)
15:19:22 <samccann> abadger - I know it' not your realm anymore, but is there somethign somewhere that documents steps for each release/ Seems we'd need to add ^^ to it
15:19:31 <samccann> abadger1999 ^^
15:20:28 <samccann> felixfontein : does this apply to both the ansible-base release and the ansible release? (since they don't happen the same day)
15:20:32 <abadger1999> Yeah....
15:20:49 <abadger1999> samccann: https://github.com/ansible/community/wiki/RelEng:-ReleaseProcess
15:21:02 <felixfontein> samccann: the ansible-base porting guide should not change
15:21:06 <abadger1999> relrod: (see above about release process updates)
15:21:42 <felixfontein> samccann: it's only the ansible porting guide which changes, since every version can have new minor versions of collections, and these can deprecate new things (they should not have removals and breaking changes, though)
15:22:02 <samccann> #action relrod to update https://github.com/ansible/community/wiki/RelEng:-ReleaseProcess with appropriate steps to keep autogenerated porting guide in sync with each release for ansible (including minor releases)
15:23:38 <samccann> ok we are down to about 7 minutes to go.
15:23:52 <samccann> #topic docs pipeline updates
15:24:05 <samccann> So we have 2.10 published to match yesterdays alpha
15:24:26 <samccann> https://docs.ansible.com/ansible/2.10/index.html - continue to poke around your fav modules/collections to see how they look
15:24:36 <samccann> any updates abadger1999 ?
15:25:09 <acozine> Hooray for 2.10 docs!
15:25:13 <abadger1999> Not directly, this week.  I'm working on redirects for probably the next two weeks.
15:25:19 <samccann> kewl
15:25:25 <samccann> one thing I wanted to info on this...
15:25:30 <abadger1999> Unsure as of yet if those will be part of the docs pipeline or a one-off.
15:25:52 <samccann> #info - the ansible docsite will mirror the collection version in the relevant ansible release
15:26:36 <abadger1999> There will be a script which reads  the runtime.yml from ansible-base and create redirects to the new module locations.
15:26:46 <felixfontein> you mean redirects from <=2.9 URLs to >=2.10 redirects? or redirects for meta/runtime.yml redirects? (or both?)
15:26:54 <felixfontein> ah, so the former
15:26:55 <samccann> #info if your collection is more recent than what is in ansible, the only way to see collection docs for the version is if you put them in your collection readme as Galaxy does not yet display module docs
15:27:20 <samccann> #info ansible docs will be republished with each minor etc release of ansible
15:27:35 <abadger1999> I'll also be looking into whether it makes sense to make redirects for plugins which have moved via the runtime.yml from collections
15:27:51 <abadger1999> But I'm not yet sure if those should be done this way or not.
15:27:54 <samccann> #info work continuing on the redirects from old module pages to new collection-based module pages.
15:28:02 <abadger1999> (and they're not the priority right now0
15:28:34 <felixfontein> abadger1999: I think that's somehow coupled with how collection scanning will be done in the future
15:28:40 <abadger1999> samccann: Cool, about the version.... do we want to talk about whether to change that in the future (to target latest version on galaxy instead)?
15:29:10 <abadger1999> Err... s/latest version on galaxy/latest compatible version on galaxy/
15:29:51 <felixfontein> would that be `devel`? and should `devel` be latest version on galaxy, or latest compatible version on galaxy, or latest git version?
15:30:07 <abadger1999> devel would use latest version on galaxy.
15:30:32 <samccann> abadger1999: we should discuss yes.  my nickel is the docs are for ansible and thus should be that version. But other opinions my differ
15:30:55 <abadger1999> (I'm not eager to get into looking at disparate git repos who may or may not be mentioned i nthe galaxy metadata and may or may not be structured the same way for every collection :-/ )
15:30:55 <felixfontein> I'd also say that the docs in /2.10/ should match the latest 2.10.x release, and not something that's newer
15:31:06 <samccann> ah sorry yes - if we can find a way for devel to be latest galaxy versions, that would be cool
15:31:09 <felixfontein> abadger1999: fully understandable!
15:31:31 <samccann> but we run into the problem of  - what if a collection has a breaking change? It wouldn't be in the next ansible version anyway, right?
15:31:40 <abadger1999> Do the stable-2.9 docs currently document the next minor release of 2.9?  (ie: the HEAD of the stable-2.9 branch)?
15:31:57 <acozine> abadger1999: yes, we republish with each new release
15:32:04 <samccann> stable-2.9 i think gets updated when 2.9 releases a dot release
15:32:10 <samccann> so it's not HEAD
15:32:14 <acozine> ah, right
15:32:28 <abadger1999> Ah, okay.
15:32:30 <acozine> we don't publish between releases, unless someone triggers a manual build
15:33:00 <acozine> the old `devel` docs got automatically republished 3x per day
15:33:04 <abadger1999> Alright, then what we're doing now with stable-2.10  matches what we're doing for stable-2.9
15:33:22 <samccann> yeah that manual build could cause problems if it picks up say a module docs change that reflects a bugfix in 2.9 that hasn't been released yet
15:33:33 <felixfontein> and usually backports are only merged very close to a release, so even if stable-2.9 docs are republished inbetween, they are usually the same
15:33:45 <felixfontein> (also there are no new features backported to stable-2.9)
15:33:47 <samccann> that's good to know
15:34:19 <samccann> #info how we handle `devel` docs wrt to collection versions is TBD
15:34:38 <samccann> anything else on the docs pipeline before we open the floor?
15:35:57 <abadger1999> Not from me
15:36:04 <samccann> #topic Open Floor
15:36:21 <samccann> Anyone around who has a question/comment/idea to discuss?
15:37:48 <samccann> I'll toss out that we are tracking the following items for the ansible release - https://github.com/ansible/ansible/projects/27#column-2809177
15:37:55 <samccann> let us know if you see gaps etc.
15:38:14 <baptistemm> is the list of doc tasks for FQCN is up to date ?
15:38:22 <baptistemm> like updating the examples
15:38:31 <samccann> probably not.
15:38:57 <samccann> it's been a 'we have to update for FQCN' thought, but I don't know that we are tracking what's fixed and what isn't anywhere
15:38:58 <baptistemm> I've almost no time so docs are fine for me
15:39:17 <baptistemm> we have update M() references
15:39:35 <baptistemm> +one PR
15:40:08 <acozine> thanks baptistemm, things are much better now than they were just weeks ago!
15:40:25 <baptistemm> I've a look later
15:40:36 <acozine> anyone who sees places where FQCN needs to be added, post a link in the chat here any time
15:40:50 <samccann> and PRs always welcome :-)
15:41:25 <samccann> if there's nothing else... will close the meeting... last chance....
15:42:23 <samccann> ok thanks everyone!
15:42:26 <samccann> #endmeeting