14:31:12 <acozine> #startmeeting Docs Working Group aka DaWGs
14:31:12 <zodbot> Meeting started Tue Aug 25 14:31:12 2020 UTC.
14:31:12 <zodbot> This meeting is logged and archived in a public location.
14:31:12 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:31:12 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:31:12 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:31:23 <acozine> #topic opening chatter
14:31:27 <acozine> who's around to talk docs?
14:31:49 <felixfontein> I'm around (half-way at least :) )
14:32:00 <acozine> I know Mr. Barker is AFK, and samccann has temporarily stepped away
14:32:05 <acozine> #chair felixfontein
14:32:05 <zodbot> Current chairs: acozine felixfontein
14:33:05 <acozine> baptistemm: belfast77 briantist cbudz cyberpear gwmngilfen madonius mrproper Pilou thedoubl3j tremble wangbaoshan__ zbr you folks around?
14:33:14 <zbr> o/
14:33:21 <acozine> #chair zbr
14:33:21 <zodbot> Current chairs: acozine felixfontein zbr
14:33:28 <baptistemm> hello
14:33:33 <samccann> hellooo!
14:33:39 <felixfontein> #chair samccann
14:33:39 <zodbot> Current chairs: acozine felixfontein samccann zbr
14:33:57 <acozine> #chair baptistemm
14:33:57 <zodbot> Current chairs: acozine baptistemm felixfontein samccann zbr
14:34:32 * gwmngilfen lurks
14:34:47 <aminvakil> I guess it's ok just to be here and listen? :)
14:35:02 <acozine> welcome gwmngilfen and aminvakil!
14:35:18 <acozine> aminvakil: yes, everyone is welcome to listen/read/watch
14:35:23 <gwmngilfen> you pinged me, so I looked 🙂 I'm here if there's data/stats stuff, I guess :)
14:36:10 <acozine> gwmngilfen: oh, yeah, I wanted to get an item on your radar for tracking traffic changes
14:36:27 <acozine> it's 3-4 items down on the agenda though
14:36:40 <acozine> agenda: https://github.com/ansible/community/issues/521#issuecomment-675555775
14:36:48 <gwmngilfen> i'll be here when you get to it ;)
14:37:05 <acozine> #topic bitflip release process
14:37:38 <acozine> felixfontein: do you know where we are with the release process?
14:37:55 <acozine> I don't want to ping anyone who might be asleep on the US West Coast
14:38:04 <felixfontein> acozine: according to the roadmap (https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/roadmap/COLLECTIONS_2_10.rst) we had beta freeze last week, and we're waiting for beta 1 next week (september 1st)
14:38:29 <felixfontein> (IMO we should shorten the intervals between last alpha and beta the next time)
14:39:00 <acozine> a tighter timeframe might be nice, and once folks have been through it once, it should be easier
14:39:08 <felixfontein> indeed
14:39:21 <acozine> but I was thinking more about the mechanics of putting the release on PyPI
14:39:24 <felixfontein> besides what I mentioned above, I think not much happened
14:39:28 <felixfontein> (at least nothing I noticed :) )
14:39:45 <acozine> heh
14:39:47 <felixfontein> sorry, no idea about that... I know that abadger1999 had a lot of meetings, maybe some were related to that
14:40:04 <acozine> okay, we'll skip that agenda item for now
14:40:29 <acozine> hm, we'll skip redirects for now also, unless anyone here has heard any news???
14:41:16 <acozine> for anybody who's new, we're talking about the first release of Ansible as a package including `ansible-base` and a set of collections
14:42:09 <acozine> the module documentation is moving from its old location at docs.ansible.com/ansible/modules/ to a new section, and the organization is changing too
14:43:03 <acozine> the organization used to reflect the filetree within the ansible/ansible repo (with directories for `database` and other types of modules), in future it will reflect the collections on galaxy.ansible.com
14:43:48 <acozine> next week I'll ask for updates about the release stuff on Monday evening
14:44:01 <acozine> #topic porting guide, changelogs, and pipeline
14:44:07 <acozine> anything new in this arena?
14:45:13 <acozine> we merged https://github.com/ansible/ansible/pull/71389
14:45:53 <felixfontein> why Monday evening?
14:46:23 <samccann> to capture a certain west coast fellah who needs to sleep around this time :-)
14:46:24 <felixfontein> acozine: nothing from my side either
14:46:30 <felixfontein> samccann: ah ok :)
14:46:39 <felixfontein> samccann: that person has been writing something in #ansible-community a few minutes back
14:46:42 <abadger1999> I spent all of last week working on beta freeze and getting code ready for beta 1. So no progress on either Jenkins jobs or redirects. This week I'm devoting to docs work, though (redirects first, then bit flipping if i have time)
14:46:48 <samccann> AAAHAHAHA
14:46:55 <gwmngilfen> :)
14:47:29 <acozine> heh, we tried
14:47:41 <acozine> welcome abadger1999
14:47:47 <acozine> #chair abadger1999
14:47:47 <zodbot> Current chairs: abadger1999 acozine baptistemm felixfontein samccann zbr
14:48:16 <acozine> are there any remaining problems with the changelogs for collections?
14:49:48 <felixfontein> acozine: except that not all collections have included changelogs/changelog.yaml, or provided a link to a changelog, I don't think so
14:50:24 <samccann> is there anyone nagging them? Or I think there is an issue in each collection for how to be in Ansible 2.10 ?
14:50:35 <acozine> felixfontein: thanks, do we have a list of no-changelog collections?
14:50:54 <felixfontein> I think g did some nagging, but I don't know for how many of these collections
14:51:12 <felixfontein> there's https://gist.github.com/felixfontein/dc49e25d1bc324f8645d1345c1177552 but that might be outdated
14:52:07 <samccann> #info this may be out of date, but 23 of 71 collections have no compatible changelogs - https://gist.github.com/felixfontein/dc49e25d1bc324f8645d1345c1177552
14:52:16 <acozine> awesome, thanks!
14:52:24 <samccann> yeah that seems like a large list.
14:52:37 <felixfontein> I'll try to update it
14:52:41 <samccann> #action samccann to nag internal partner team to nag partners on changelogs
14:52:47 <acozine> about 30% or so
14:53:28 <samccann> yeah that would be helpful  felixfontein. Ping me w/ and updated list. A lot of those look to be partner folks so we have a person/persons we can nudge to go nudge them some more (or at least find out if they never plan on doing it)
14:54:46 <samccann> what about porting guide - anything we need to continue to nag/worry/fix?
14:57:04 <acozine> the porting guide seems to be working well
14:57:26 <samccann> kewl
14:57:41 <samccann> shall we move on to the TOC changes?
14:57:44 <acozine> sure
14:57:52 <acozine> #topic updated User Guide TOC
14:58:17 <acozine> gwmngilfen: this is the one I'm hoping you can help us evaluate over time - do changes to the TOC affect traffic patterns?
14:58:56 <acozine> there's no PR yet, but here is a preview of the changes I've got so far: http://docs.testing.ansible.com/ansible/devel/user_guide/index.html
14:59:10 * gwmngilfen is kinda here, also in a meeting
14:59:20 <felixfontein> acozine: samccann: the list is still up to date
14:59:31 <samccann> ok thanks!
15:00:01 <acozine> gwmngilfen: I can ping you again later, when your whole brain can engage
15:00:12 <baptistemm> (sorry I working so can't read thoroughly)
15:00:27 <felixfontein> acozine: samccann: please note that collections must release patch versions (w.r.t. to the frozen lower version in https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible-2.10.build) so they have a chance to show up in 2.10.0
15:00:29 <samccann> meanwhile, I mentioned moving playbooks before inventory, but that might require re-reading those sections
15:00:29 <gwmngilfen> gimme 10min or so :)
15:00:41 <felixfontein> i.e. if they add a changelog in the next minor release, the changelog will only appear in ansible 2.10.1
15:01:03 <baptistemm> acozine: for the TOC, what are the objectives ?
15:01:11 <samccann> #info for changelogs to show up in 2.10.0 collections must release patch versions (w.r.t. to the frozen lower version in https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible-2.10.build) so they have a chance to show up in 2.10.0
15:01:25 <acozine> felixfontein: so for collection 2.3.4 they need to release 2.3.5, right?
15:01:29 <samccann> #info w.g. they add a changelog in the next minor release, the changelog will only appear in ansible 2.10.1
15:01:34 <acozine> and not do it as 2.4.0
15:01:39 <felixfontein> acozine: yes
15:01:46 <acozine> gotcha, thanks
15:02:02 <felixfontein> one of the collections (cisco.ucs) already released a new minor version which won't be in 2.10.0
15:02:08 <felixfontein> (again without changelog)
15:02:35 <acozine> baptistemm: 1. to get all the User Guide pages linked from the guide's main index pages - right now we have sub-TOCs that are hard to find
15:02:42 <samccann> #info cisco.ucs) already released a new minor version which won't be in 2.10.0
15:03:09 <acozine> for example, https://docs.ansible.com/ansible/latest/user_guide/playbooks.html
15:03:15 <baptistemm> acozine: I need to write down everything that puzzle me about that
15:03:39 <acozine> some of the pages on that sub-TOC don't appear in the main TOC
15:03:40 <baptistemm> #todo baptistemm to to write down everything that puzzle him about ansible docTOC
15:03:57 <acozine> heh
15:03:57 <baptistemm> #action baptistemm to to write down everything that puzzle him about ansible docTOC
15:04:11 <acozine> and that sub-TOC has a sub-sub-TOC: https://docs.ansible.com/ansible/latest/user_guide/playbooks_special_topics.html
15:04:12 <baptistemm> meh
15:04:42 <acozine> another goal is to make the left-hand navigation cleaner
15:05:09 <acozine> right now when you're on a page within the User Guide, you see a long list of specific topics in the left nav
15:05:37 <baptistemm> exactly, I'd prefer having more sub entries under Using ansible
15:05:56 <baptistemm> or just entries
15:06:12 <baptistemm> don't know how to say, sibling of User Guide
15:06:49 <samccann> ah so you are thinking the user guide itself it soo big of a single 'guide' to be usable?
15:06:55 <acozine> compare the left nav on https://docs.ansible.com/ansible/latest/user_guide/playbooks_error_handling.html with the left nav on http://docs.testing.ansible.com/ansible/devel/user_guide/playbooks_error_handling.html
15:06:57 <baptistemm> yep
15:07:12 <samccann> as in separate out - playbooks, variables, inventory into their own top-level 'guides' ?
15:07:27 <acozine> yeah, that's kind of what I was trying to do with the "sections" on the testing page
15:07:28 <baptistemm> I would prefer having a starting guide and then a topic to going deeper in a topic
15:07:47 <baptistemm> a topic to go deeper in a subject
15:08:03 <samccann> yeah baptistemm - try the left-hand navigation in acozine's test. it does some of that now
15:08:43 <samccann> theres a need to reconsider/redesign all of the docs...(aka big project, will take ages) and then there's the 'what can we do in the meanwhile to make things better).
15:09:05 <acozine> almost all of the content in that guide is reference material - it's not "do these steps in this order" it's more "this is what this feature means"
15:09:06 <samccann> This test is that second category ' what can we do to make things better for now)
15:10:30 <baptistemm> at least I see there is a general improvement
15:11:37 <samccann> my nickel - acozine - create a PR and then folks can add comments.  Like if baptistemm sees other ideas of what should show up in that left-hand nav for the user section
15:11:52 <acozine> sounds good
15:11:55 <baptistemm> we should have more seperation between target readers: playbook developer (sysadmin), role, module, collection developer
15:12:06 <acozine> there are still things I know I need to fix before I open a PR
15:12:17 <baptistemm> acozine: great
15:12:28 <acozine> baptistemm: the role/module/collection developer stuff should all be in the Dev Guide
15:12:38 <samccann> baptistemm: yes, that's part of the Great Docs Redesign  (just made up that name).  But we know we have to split things out base on who is reading it, just like you said
15:12:44 <acozine> well, module/collection, at least
15:12:53 <acozine> I guess role developer is kind of in-between
15:13:01 <baptistemm> yes
15:13:24 <baptistemm> s/role,//
15:14:59 <acozine> thanks for the feedback, ping me here any time with comments/suggestions/questions about the TOC
15:15:32 <acozine> also, please remember that materials on the testing site may disappear or change at any time with no warning
15:16:40 <samccann> felixfontein - on the changelogs - is there a deadline by which no further changelog items will show up for 2.10?  Is that like the date the package is created or something sooner?
15:18:56 <samccann> oh shoot, I didn't info anything about t he toc!
15:19:30 <acozine> ah, that's okay
15:19:48 <samccann> #info user guide TOC update in progress to improve overall navigation and findability. http://docs.testing.ansible.com/ansible/devel/user_guide/index.html
15:20:03 <samccann> #info that link may not stay active with the proposed changes but PR will come
15:20:30 <samccann> #info we should have more seperation between target readers: playbook developer (sysadmin), role, module, collection developer
15:20:59 <acozine> abadger1999: felixfontein is there a deadline for changelogs from collections?
15:22:42 <acozine> #action acozine to follow up on deadline for collections changelogs
15:23:24 <samccann> i'd like to see us find out what the hard deadline is, and then make a procedural deadline before that. I fear 30 collection owners coming here all on the same day looking for help
15:23:32 <samccann> (that day being the last possible day for inclusion )
15:23:39 <acozine> samccann: yep, that could easily happen
15:23:47 <gwmngilfen> acozine: back ;)
15:24:40 <acozine> gwmngilfen: we're looking at redesigning the User Guide TOC (initial changes can be viewed at http://docs.testing.ansible.com/ansible/devel/user_guide/index.html) and would like to track the influence of any changes on web traffic
15:24:54 <acozine> esp. whether previously obscure pages start seeing more traffic
15:25:12 <gwmngilfen> hmm
15:25:21 <gwmngilfen> how far back do the Adobe web stats go?
15:25:34 <acozine> at least 18 months, probably longer
15:25:54 <abadger1999> Probably rc1.
15:26:00 <gwmngilfen> assuming we have something simple like "unique hits per day" or similar, and we make a note somewhere of the day the change goes live, then we can do some analysis, yes
15:26:07 * abadger1999 finding the date for that now
15:26:07 <acozine> gwmngilfen: awesome
15:26:48 <felixfontein> samccann: as abadger1999 said, the latest rc, since there will be no difference between the latest rc and 2.10.0
15:26:58 <abadger1999> 2020-09-10: ansible-2.10 final freeze/rc1.
15:27:10 <gwmngilfen> for a given page, it's trivial enough, you have a time-series of counts before the change, you forceast the line, and then plot the real counts after the change - if they look super-different, you had an effect
15:27:45 <acozine> samccann: so, maybe Sept 7 (Monday) for the procedural deadline?
15:28:06 <samccann> yeah was thinking the same thing
15:28:30 <samccann> anyone know the schedule of the next Bullhorn? would be a good place to communicate that date
15:28:40 <gwmngilfen> acozine: now, aggregating that over a range of pages-of-interest is probably what we need, I'll need to have a think about that, but in principle it should work
15:28:41 <samccann> assuming it comes out soon. :-)
15:28:50 <acozine> hmm, I think it just went out . . . but we should check
15:28:54 <gwmngilfen> bullhorn is usually every 2 weeks
15:29:25 * gwmngilfen pokes cybette
15:30:07 <gwmngilfen> acozine: in any case, so long as we have the traffic data, we can attempt something. the biggest risk is competing events - if *other* things change during the study window, it muddies the water
15:30:12 <acozine> #agreed collections changelogs are due by Monday, September 7 for the 2.10.0 release
15:30:12 <samccann> ok looks like it went out maybe 5 days ago. So we could get it to people sort of in time
15:30:30 <acozine> gwmngilfen: yeah, like Fest . . .
15:30:35 <acozine> still, it's worth looking at
15:30:36 <gwmngilfen> right
15:30:47 <gwmngilfen> or new releases :)
15:30:52 <samccann> #action samccann to add Mon sept 7 deadling for changelogs to the next BullHorn and consider where else it should be announced
15:30:52 <acozine> or that, yeah
15:31:08 <acozine> heh, I like `deadling`
15:31:22 <acozine> #topic open floor
15:31:23 <gwmngilfen> we'll want to make a note of such things, we can try to account for them, especially if we have data from last year to condition with
15:32:13 <gwmngilfen> I'd hope we have 2 years worth, that would enable some fancy tricks :)
15:32:27 <gwmngilfen> acozine: when is this change due to go live?
15:32:47 <acozine> gwmngilfen: "not yet" is the best I can tell you, it isn't even finished
15:32:48 <samccann> hahah deadling
15:32:59 <acozine> but I wanted to get it on your radar
15:33:05 <gwmngilfen> heh, fair enough
15:33:16 <baptistemm> about doc, I saw there a japanese version, is ther any translation support planned ?
15:33:39 <gwmngilfen> would you take an action to see how far back the analytics data goes? if it's <2 years, we should probably download a bunch of the old data now
15:33:39 <acozine> baptistemm: what do you mean by "translation support"?
15:34:17 <acozine> #action acozine to find out how many months or years of web traffic analytics data we can access
15:34:35 <gwmngilfen> thanks, I'd do it but I'm swamped right now ;)
15:34:42 <baptistemm> acozine: french, german, ... using standard method existing in software like gettext or wahtever
15:34:47 <acozine> the japanese version of the docs was done by the RH localization team
15:35:01 <acozine> ah, other languages
15:35:28 <gwmngilfen> acozine: the other action would be: between now and $whenItsDone we'll want to decide which pages we're interested in. and don't say "all of them" :P
15:35:35 <acozine> heh
15:35:58 <acozine> #action acozine to decide which User Guide pages we want TOC-change data on
15:36:14 <gwmngilfen> i'm going to assume it's the stuff linked from the user stories
15:36:27 <gwmngilfen> but making an explicit list is probably wise
15:36:55 <samccann> user stories??? you got user stories for Ansible???
15:37:01 <acozine> baptistemm: they decided on japanese because we have a lot of users and customers in Japan, and for many of them the language barrier to English is high
15:37:15 <gwmngilfen> well, i mean the stuff above the traditional-toc
15:37:33 <samccann> oh aha you got me all excited about formally defined user stories
15:37:45 <gwmngilfen> heh, bad choice of words, sorry :)
15:37:49 <samccann> :-)
15:37:57 <acozine> if they do other languages, the next ones might be Spanish or Portuguese or Chinese . . .
15:38:05 <samccann> just wishful thinking on my part
15:38:51 <gwmngilfen> for the record, as an Ansible novice, i think that draft looks great :)
15:39:31 <acozine> aminvakil1: as you can see, the `open floor` section of the meeting is when everyone chimes in about whatever is on their minds - it can be an issue or PR on GitHub, or a question about the docs or related topics, or anything, really
15:40:08 <acozine> aminvakil1: if you're still around, would you be comfortable sharing what interests you about Ansible documentation, why you joined the IRC channel, etc.?
15:41:00 <gwmngilfen> cybette says next week for bullhorn, conent to be in by Monday if possible
15:41:09 <acozine> thanks gwmngilfen
15:41:10 <gwmngilfen> published Wed
15:41:34 <aminvakil1> acozine: I have nothing in mind, just reading and watching.
15:41:44 <aminvakil1> thanks for asking though.
15:41:50 <acozine> aminvakil1: good to have you hear
15:41:54 <acozine> er, here
15:41:55 <acozine> heh
15:42:09 <acozine> both hear and here, I guess ;-)
15:42:13 <aminvakil1> :)
15:42:40 <acozine> all right, as usual lately, we've gone over our one-hour meeting
15:42:52 <acozine> anybody have a last question, comment, concern?
15:43:02 <acozine> a PR we should look at and if possible merge?
15:44:37 <acozine> hearing none . . .
15:44:42 <samccann> Reviews/comments of open docs issues always welcome and helps move them along to being merged - https://github.com/ansible/ansible/pulls?q=is%3Aopen+is%3Apr+label%3Adocs
15:44:56 <acozine> agenda items are always welcome, just add a comment to https://github.com/ansible/community/issues/521
15:45:36 <acozine> thanks abadger1999 aminvakil1 baptistemm gwmngilfen samccann zbr
15:45:49 <gwmngilfen> :+1:
15:46:02 <acozine> dang, I tried to alphabetize and missed felixfontein
15:46:03 <acozine> thanks felixfontein
15:46:20 <baptistemm> time for pool diving
15:46:23 <baptistemm> see you later
15:46:32 <acozine> that's it for this week's formal meeting, chat welcome in the channel any time
15:46:35 <acozine> #endmeeting