15:09:13 <acozine> #startmeeting Docs Working Group
15:09:13 <zodbot> Meeting started Tue Jul 16 15:09:13 2019 UTC.
15:09:13 <zodbot> This meeting is logged and archived in a public location.
15:09:13 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:09:13 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:09:13 <zodbot> The meeting name has been set to 'docs_working_group'
15:09:36 <acozine> #topic saying farewell to Python 2 in the docs build
15:09:42 <acozine> who's around?
15:09:42 <samccann> Partially here
15:09:49 <acozine> #chair samccann
15:09:49 <zodbot> Current chairs: acozine samccann
15:10:31 <samccann> Hmm more like an observing end table for the next few minutes
15:11:01 <acozine> cyberpear: alongchamps andersson007_ belfast77 brtknr dag dfed felixfontein jhawkesworth jmnk mrproper orthanc Pilou shaps theo-o Xaroth8 zoredache you really here, or just logged in?
15:11:25 <jhawkesworth> I am actually here
15:11:36 <acozine> #chair jhawkesworth
15:11:36 <zodbot> Current chairs: acozine jhawkesworth samccann
15:11:51 <acozine> jhawkesworth: welcome!
15:12:15 <acozine> thanks for joining the Docs WG, aka DaWGs
15:12:56 <alongchamps> just logged in
15:12:58 <acozine> Our plan is to merge the changes to the docs build, along with several other changes to various utilities, this week
15:13:14 <acozine> alongchamps: heh, sounds good - join in if/when you can
15:13:48 <jhawkesworth> sounds like a good idea to me.  Still some time left before 2.9 release for any unforeseen issues to be ironed out
15:13:49 <acozine> PR for the python-2-to-python-3 change: https://github.com/ansible/ansible/pull/55986
15:14:37 <acozine> jhawkesworth: agreed - the timing is good, but I wanted to be sure anyone who had reasons for sticking with python 2 had a chance to chime in
15:15:18 <acozine> we didn't want to merge it over the US holiday and surprise folks
15:15:27 <jhawkesworth> fair enough!
15:15:56 <acozine> the PR touches lots of files, so it needs a lot of rebasing - we will likely merge it today unless there's a last-minute objection
15:16:24 * acozine feels like the minister at a wedding . . . "if anyone here knows of any reason why this shouldn't happen, speak now or forever hold your peace"
15:16:39 <jhawkesworth> just quickly surfing through the pr to see if there's a changelog entry
15:17:36 <acozine> I don't know if there is
15:17:41 <jhawkesworth> doesn't seem to be.
15:17:43 <acozine> it does update the docs about building the docs though
15:17:46 <acozine> https://github.com/ansible/ansible/pull/55986/files?file-filters%5B%5D=.j2&file-filters%5B%5D=.py&file-filters%5B%5D=.rst&file-filters%5B%5D=.txt&hide-deleted-files=true#diff-0047c06dfbe923021df8d46a96f12dceR63
15:17:54 <jhawkesworth> fair enough.
15:18:12 <acozine> changelogs are more for user-facing changes
15:18:17 <jhawkesworth> i know its 'internal'.   I'm not going to object to merging.
15:18:48 <acozine> thanks for speaking up - it's good to look and make sure we're following our own guidelines
15:19:04 * acozine looks for documentation of when changelogs are required
15:19:12 <jhawkesworth> just worth a mention I guess on ansible-project and irc channels, for those like me who sometimes build docs locall
15:19:29 <acozine> jhawkesworth: good idea
15:19:30 <jhawkesworth> pretty sure changelogs are for bug fixes and functional changes.
15:19:52 <acozine> https://docs.ansible.com/ansible/devel/community/development_process.html?#changelogs
15:20:08 <acozine> "You must add a changelog fragment to any PR that changes functionality or fixes a bug. "
15:20:36 <acozine> so we should probably add one, since this does change functionality, even if it is internal
15:20:56 <jhawkesworth> does it.. the output should be the same (or is it not)?
15:21:07 <acozine> the output is the same
15:21:35 <jhawkesworth> then its an 'engineering change' - users should not be affected so its fine, in my opinion
15:21:36 <acozine> at least, the intention is to create the same output, and we haven't uncovered cases where that fails . . .
15:22:14 <acozine> I know some folks have python 2 still on managed nodes
15:22:32 <acozine> but I hope most folks have python 3 on their dev machines and control nodes already
15:22:52 <jhawkesworth> erm.. some of them
15:22:59 <acozine> I like the phrase "engineering change"
15:23:07 * jhawkesworth adds python 3 installs to TODO list
15:23:27 <acozine> heh, okay, so some education and publicity is a good idea once we merge this
15:23:28 <jhawkesworth> its not mine, but can't remember where I heard it
15:23:44 <jhawkesworth> that sounds like a good plan to me.
15:24:42 <acozine> #agreed docs team will publicize the python-3-for-docs change in multiple IRC channels and on mailing lists
15:24:55 <acozine> hm, is that not the right command?
15:25:14 * acozine still wrestles with IRC meetings
15:25:43 <jhawkesworth> not sure but also possible zodbot is asleep
15:25:48 <acozine> all right, last call for comments on PR 55986, which moves the docs build to python 3 . . .
15:26:01 <acozine> going once . . .
15:26:11 <jhawkesworth> bring it on
15:26:13 <acozine> going twice . . .
15:26:24 <acozine> SOLD to the Ansible community for a single PR merge
15:26:46 <acozine> #topic docsite updates/improvements/changes
15:26:51 <jhawkesworth> polite applause
15:27:01 <samccann> Woot
15:27:06 <acozine> golf clap
15:27:35 <samccann> Here for realz now
15:27:54 <acozine> cyberpear: regarding your comment earlier about the version-changer for 2.4 docs . . .
15:28:06 <acozine> 2.4 is EOL now - no security updates
15:28:20 <acozine> so we are trying to encourage folks to upgrade
15:28:31 <acozine> that's why we didn't add it as an option on the version-switcher
15:29:33 <acozine> we are working on banners for EOL versions to warn users - those will probably feature one-way links to `latest`
15:31:18 <acozine> other docsite imrpovements we've been considering:
15:31:26 <acozine> more responsive module docs
15:32:48 <jhawkesworth> curious what 'more responsive module docs' means
15:33:27 <acozine> jhawkesworth: things like https://github.com/ansible/ansible/issues/57679
15:33:57 <acozine> it's not just the module docs, but they may be the worst offenders
15:34:10 <acozine> related issues include 51992 and 56619
15:34:28 <jhawkesworth> ah ... responsiveness to screen layout.. nice
15:34:48 <acozine> other recent achievements include better breadcrumbs
15:34:54 <jhawkesworth> since I'm here... the cloud modules page is huge now.
15:35:03 <acozine> ah, yes
15:35:08 <acozine> better index pages
15:35:39 <acozine> though most traffic comes straight from google search to individual module docs pages
15:35:47 <jhawkesworth> I've only just recently realized there's anchors on each section so I can go straight to the cloud I'm working on at the moment.  https://docs.ansible.com/ansible/latest/modules/list_of_cloud_modules.html#azure
15:36:03 <acozine> yeah, that has been there for a long time
15:36:21 <samccann> ‘Back in the day’ ( i.e) I had an idea how to add toc to the top of those pages
15:36:24 <acozine> we considered adding a local TOC to make those obvious, but it would just add to the scrolling
15:36:27 <jhawkesworth> I sometimes wish the Module Index was somehow more visually differentiated from the other left menu items
15:36:38 <samccann> Problem was yeah loads of scrolling
15:37:51 <samccann> And not sure how collections impacts this in the future
15:38:09 <jhawkesworth> hmm, good point about collections.
15:39:09 <samccann> Can you describe how you use the cloud modules docs today? Would help us imagine what folks need in a collection of these
15:40:36 <jhawkesworth> well I'm on a project to do stuff in azure, so typically I start google searching for a module name like 'ansible azure_rm_<something>
15:40:59 <acozine> how often does that get you what you need?
15:41:27 <jhawkesworth> I hit the cloud page and then scroll a lot, (unless I look for the anchor).
15:41:44 <acozine> (also, can i just say that every time I read `azure_rm_whatever`, in my mind I read "Azure Remove Whatever")
15:42:03 <jhawkesworth> yeah rm is hardcoded in my brain too
15:42:21 <acozine> jhawkesworth: ah, so the google search generally sends you to that index page, not to an individual azure module?
15:42:24 <acozine> interesting . . .
15:42:46 <jhawkesworth> hard thing with azure is getting parameters right.  so I can see what there are modules for quickly, but getting the detail right takes the time.
15:42:46 <samccann> Yeah wasn’t sure why that happens
15:43:34 <jhawkesworth> more examples of real things people need to do and links to context, but this is getting specific to modules of this type, rather than being a generic documentation issue
15:43:50 <jhawkesworth> sorry I'm going to have to drop now, train to catch
15:43:53 * jhawkesworth afk
15:43:56 <acozine> I've been reviewing a lot of updates to their module docs recently - I'd welcome additional eyes if you have time for reviews
15:44:06 <acozine> jhawkesworth: travel safe
15:44:31 <acozine> heh, I forgot to bring up the question of moving this meeting earlier . . .
15:44:54 <acozine> I think we should do that by fiat - so many folks are in the UK/EU time zones
15:45:40 <samccann> +1 for earlier
15:46:33 * acozine sighs and checks stock of caffeinated tea
15:46:51 <acozine> all kidding aside, I'm +1
15:47:21 <acozine> anything else to discuss for docsite improvements?
15:48:42 <acozine> hearing none . . .
15:48:45 <acozine> #topic open floor
15:49:23 <acozine> open to any question, concern, idea, suggestion, complaint, compliment, or comment
15:49:54 <acozine> I'll post a few updates
15:50:11 <acozine> we've been keeping the open docs PR count under 75 consistently
15:50:15 <samccann> Have we ever tried a docathon?
15:50:33 <acozine> not while I've been here, no
15:50:49 <acozine> I'd support one for sure
15:50:50 <cyberpear> any chance of re-opening this one? https://github.com/ansible/ansible/pull/57318
15:51:39 <cyberpear> would be good to backport to 2.8 so folks reading the docs can know all the available options
15:51:55 <acozine> cyberpear: that's an interesting PR - yes, we should document that option
15:52:36 <cyberpear> there's been a lot of discussion on the related ticket https://github.com/ansible/ansible/issues/56930
15:53:01 <acozine> I haven't read https://github.com/ansible/ansible/issues/56930 thoroughly
15:53:09 <cyberpear> that option resolves most of the gripes there
15:53:44 <cyberpear> (the ticket is mostly gripes about the change, but the undocumented option allows folks to go back to the old behavior w/o warnings)
15:54:22 <acozine> I like incremental progress, so I'm inclined to re-open and merge that PR
15:54:47 <acozine> let me make sure a more comprehensive fix isn't 99% of the way done before I do, though
15:54:56 <cyberpear> sounds good
15:55:04 <acozine> thanks for the work you put in on the PR
15:55:57 <acozine> #agreed acozine will investigate PR 57318 and any other work being done to address issue 56930
15:56:27 <acozine> samccann: so, how would we organize a docathon?
15:56:31 <acozine> have you done one before?
15:56:56 <acozine> either as an organizer or as a participant?
15:57:46 * cyberpear thinks a better name for `TRANSFORM_INVALID_GROUP_CHARS` would be `TRANSFORM_UNSAFE_GROUP_CHARS`, as mentioned (I think) in the linked issue ^
15:58:07 <acozine> ah, names . . .
15:58:40 <samccann> Haven’t done one but seems like it could be fun. The idea is you pick an area and peeps address the problems of what’s missing or unclear
15:59:07 <acozine> ah, so crowdsourcing both the list of fixes to be made and the effort to fix them?
15:59:19 <acozine> that does sound fun . . .
15:59:26 <samccann> Yeah something like that
15:59:26 <acozine> and a possible use for DaWGs swag ;)
15:59:42 <samccann> Or host a live one at ansible fest
16:00:14 <acozine> that would be cool
16:00:25 <samccann> Usually it’s a group of peeps in a conference room for three days and they bang out a full giude
16:00:54 <samccann> Might be helpful for collections if the timing is right
16:01:14 <acozine> ah - that isn't realistic for AnsibleFest, but maybe we could plan an online one for the fall
16:01:29 <acozine> where "that" is "three days in a conference room"
16:01:50 <samccann> Yeah was thinking that as well
16:02:01 <acozine> let's explore format/timing/organization - it's a good idea
16:02:32 <acozine> #agreed docs team and channel to explore a docathon
16:02:41 <acozine> yikes, I have to run to my next meeting
16:03:20 <acozine> thanks, folks - talk to you next week for another Ansible Docs Adventure
16:03:33 <acozine> #endmeeting