14:34:23 <samccann> #startmeeting DAWGS (Documentation Working Group)
14:34:23 <zodbot> Meeting started Tue Jan 28 14:34:23 2020 UTC.
14:34:23 <zodbot> This meeting is logged and archived in a public location.
14:34:23 <zodbot> The chair is samccann. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:34:23 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:34:23 <zodbot> The meeting name has been set to 'dawgs_(documentation_working_group)'
14:34:28 <samccann> anyone around?
14:35:08 <acozine> I'm half here
14:35:27 <cbudz> also half here
14:35:47 <samccann> heh
14:35:54 <samccann> #chairs cbudz acozine
14:36:00 <samccann> hmm
14:36:05 * acozine sings the old Monty Python tune "Eric the Half-a-Bee"
14:36:07 <samccann> #chair cbudz acozine
14:36:07 <zodbot> Current chairs: acozine cbudz samccann
14:36:21 <samccann> anyone else hanging around today?
14:37:45 <samccann> Well let's get started
14:37:52 <samccann> #topic Status Updates
14:38:23 <acozine> I can give an update
14:38:24 <samccann> I'll start - I pushed out the single search to 'latest' yesterday.
14:38:35 <acozine> hooray!
14:38:44 <samccann> #info left hand search is now using swiftype search on 'latest'
14:38:54 <samccann> There's a style glitch I'm still working on.
14:39:00 <samccann> yer up next acozine !
14:39:07 <acozine> mine is short
14:39:16 <acozine> my long-running User Guide PR finally got merged
14:39:23 <acozine> thanks to everyone who looked at it
14:39:32 <cbudz> excellent, congrats on that
14:39:56 <samccann> #info User Guide PR merged!!  Improved the flow of sections of the Ansible User Guide
14:40:06 <acozine> I'll do at least one more revision on the User Guide, maybe two
14:40:23 <acozine> there are still some pages I haven't re-organized
14:40:52 * acozine rubs hands together with a creepy laugh
14:40:57 <samccann> #info continued work coming on other sections of the User Guide
14:41:08 <cbudz> I left some comments on a few PRs yesterday, still in progress with updating collections doc and creating ansible_user doc
14:41:10 <samccann> good stuff!
14:41:27 <acozine> cbudz: great
14:41:37 <samccann> #info work coming on updating collections doc and creating ansible_user doc
14:41:43 <samccann> what is the ansible user doc?
14:42:06 <cbudz> discussed here two weeks ago, based on this: https://www.reddit.com/r/ansible/comments/eo6lwq/why_is_ansible_user_not_defined_when_accessed/
14:42:17 <samccann> ah thanks!
14:42:32 <samccann> #link  based on this: https://www.reddit.com/r/ansible/comments/eo6lwq/why_is_ansible_user_not_defined_when_accessed/
14:42:35 <samccann> :-)
14:42:39 <acozine> oh, we should talk about the Search Box controversy on reddit
14:42:54 <samccann> ok are there any other status updates first?
14:43:51 <samccann> ok then moving on!
14:44:01 <samccann> #topic Search box on docs.ansible.com
14:44:26 <samccann> This topic came up on reddit. The gist of it is that the main docs page is confusing and has no site search.
14:44:51 <samccann> anyone have the link handy?
14:45:59 <samccann> ok found it
14:46:04 <samccann> #link https://www.reddit.com/r/ansible/comments/eu4jat/mindblowing_docsansiblecom_does_not_have_a_search/
14:48:29 <samccann> So that main page (docs.ansible.com) has links to other ansible documentation (including Tower and Galaxy for example).  While each documentation section/site has its own search, there isn't one that allows a user to search across all of them.
14:48:53 <cbudz> how challenging is that upgrade?
14:49:20 <acozine> well, to make it work, we'd need consolidated search across all the docsites
14:49:22 <samccann> I personally have no idea how to put up a search that would go across all those documentation subsites
14:49:24 <acozine> Tower/Engine/etc
14:49:55 <acozine> but I think a redesign of the page would help a lot, without necessarily adding consolidated search
14:49:56 <samccann> A suggestion came up that we could put a link on that page to all the other search options but even that I don't know how to do
14:50:48 <cbudz> there is a lot of scrolling on the main docs page
14:50:51 <samccann> the individual search options are not a url... they are sections one each page for example
14:50:58 <acozine> that landing page needs work
14:51:15 <acozine> we've had a design for it for a while, but no resources to implement it
14:51:18 <samccann> cbudz yeah that page has some real redesign needs.  and maybe if it were simplified, it might help
14:51:43 <cbudz> A table with links to the main topics on that page might be a simplified approach to redesign
14:51:53 <samccann> #info each docsite (ansible, galaxy, tower) has its own search but nothing on the top page allows for a cross-site search)
14:52:20 <samccann> #info docs.ansible.com is also a confusing page with a lot of content. needs to be simplified/redesigned
14:53:40 <cbudz> would also like to see this sentence revised: "Ansible releases a new major release of Ansible approximately three to four times per year."
14:53:42 <samccann> There was talk about like an embedded google sitesearch, but even that might be problematic (not to mention costly) - galaxy docs today are not on docs.ansible.com - they are just linked to it from there.
14:55:04 <samccann> cbudz - open a PR?  I'm not sure we are at three to four times a year anyway.
14:55:25 <cbudz> will do.
14:56:08 <samccann> one other tidbit that came from that reddit thread that I didn't know - duckduckgo has 'bang' support for site-based search.
14:56:42 <samccann> #info on duckduckgo, you can type !ansible loops  and get search results from docs.ansible.com only
14:57:12 <acozine> that is very cool
14:57:15 <samccann> #info on duckduckgo, you can also use !galaxy or !ansiblemod yum to get directly to the yum module docs page for example
14:57:21 <samccann> yeah!  very fun
14:58:09 <samccann> well, I don't have a lot of ideas on how to solve the cross-site search.  Gonna move on for now but anyone popping in to this channel later, would love to brainstorm options
14:58:46 <samccann> do we have other topics before we move on to prs and issues?
14:59:12 <samccann> oh yeah there was some chatter on the channel before the meeting, let's capture that in the minutes
14:59:24 <samccann> #topic View vs Edit Github links
14:59:47 <samccann> #info would be nice if a reader has the option to click view on github instead of always edit on gitub
15:00:00 <acozine> that's just so people don't have to be logged in?
15:00:12 <acozine> what happens if you click on Edit on GitHub if you aren't logged in?
15:00:25 <samccann> cyperpear felixfonein - you around to hop on this question?
15:01:15 <samccann> I haven't tried the link w/o being logged in. Does it just not work?
15:01:39 <acozine> I don't know, I'm always logged in
15:02:36 <cbudz> let's see
15:02:48 <acozine> I'm logging off
15:02:54 <cbudz> just takes you to a log in screen for github
15:03:05 <samccann> yeah that's the problem then.
15:03:18 <cbudz> what's the expected functionality?
15:03:33 <acozine> that's what i would expect
15:03:36 <samccann> #info if you aren't logged into github, the Edit on Github link takes you to the login page, not the content you wanted to edit. So you have to be logged in to even view the page
15:03:59 <acozine> I'm not sure what the use case is for looking at the source without being able to edit it
15:04:15 <acozine> I suppose I'm being unimaginative
15:04:17 <samccann> fwiw edit on github is built into the RTD theme.  I'm not sure how easy it would be to extend it to have both edit and view on github.
15:04:29 <samccann> acozine - my guess is module pages
15:04:52 <samccann> you want to see the module code for some reason, aren't logged in, so can't easily 'see' it with that link
15:04:58 <samccann> that's just a random guess tho
15:05:34 <samccann> the OP was asked to open a feature request so might get more details that way
15:06:07 <samccann> #info possibly this is useful for module pages, where a developer wants to quickly scan the code but not edit it.
15:06:34 <samccann> There was one other tidbit I'd like to capture in the meeting notes, but are there any other comments/discussion about the above before we move on?
15:07:39 <samccann> ok moving on then
15:07:52 <samccann> #topic Putting module names in changelog fragments
15:08:18 <samccann> #info some changelog fragments talk about adding a parameter etc, but don't actually name the module it applies to
15:08:35 <acozine> oh, interesting
15:08:47 <acozine> we should definitely check on that
15:09:06 <samccann> i think we can make sure this is mentioned in the docs, but I feel like the best thing we can do is educate those who merge module code changes etc
15:09:13 <acozine> true
15:09:29 <samccann> I don't know that the docs folks here see all those changes. they may get merged before we see them
15:09:49 <samccann> do those changes always get the docs label?
15:10:51 <acozine> I think so
15:11:17 <acozine> I think anything with a changelog gets marked docs
15:11:34 <samccann> ok cool
15:12:05 <samccann> #agreed update the changelog guidelines to ensure it says included all relevant info including module names etc
15:12:36 <samccann> #agreed find a way to spread this need to those who merge module changes etc
15:13:48 <samccann> ok  ...moooovin on
15:14:18 <samccann> acozine - I'd like to do an open floor before doing docs prs and issues.. does that make sense?
15:14:25 <acozine> sure
15:14:28 <acozine> go for it
15:14:34 <samccann> #topic Open Floor
15:14:50 <samccann> Anyone have anything they want to bring up before we do the clean sweep to docs Issues and Prs?
15:15:14 <cbudz> nothing here
15:16:06 <cyberpear> Its helpful to see the "View on Github" for the reason of being able to track recent changes to the docs page.
15:16:28 <cyberpear> w/o being logged in vs "Edit on Github"
15:16:32 <samccann> ah thanks cyberpear!  Can you add that tibit to the issue when you open it?
15:16:34 <acozine> cyberpear: so you'd be looking for the history of the page?
15:16:42 <cyberpear> A "View history on Github" would also work
15:17:21 <samccann> can you elaborate on why you are looking for doc diffs?
15:17:29 <cyberpear> yes, it's usually to check what changed recently, or to "git blame" to see why something is the way that it is
15:17:41 <cyberpear> "is this a typo, or was it that way on purpose?"
15:17:51 <acozine> heh
15:17:59 <acozine> if you're asking, it's usually a typo ;-)
15:18:22 <cyberpear> usually the commit that changed the docs also changed the module or plugin it's referecing, so you can see which code changes went along w/ the docs change
15:18:26 <acozine> so it's not about being logged out, so much as about a different way of looking at the source
15:19:06 <cyberpear> plus being logged out -- w/ 2FA enforcement on the ansible org, I'm logged in much fewer places where I may be looking at the docs
15:20:11 <cyberpear> if I'm logged in, i just edit the URL to make it the "view" vs "edit" whereas if I'm logged out, I click the link, say "oops" -> back, copy/paste the link, tweak it, then finally get to the right place
15:20:34 <acozine> that does sound annoying
15:20:49 <samccann> #info for Edit vs View on Github - an example would be finding a doc change and wanting to find the code change that matched it. So view the file on github, find the commit/pr, and find what code changed underneath.
15:21:14 <cyberpear> sometimes the edit on github link seems to take you to a non-existent page, but that's probably a separate issue
15:21:39 <samccann> yeah the plugins I think still don't have edit on github support yet.
15:22:03 <samccann> there's an issue open for that already i think. sounds familiar anyway
15:23:20 <acozine> I just tried it
15:23:31 <acozine> you can use Edit on GitHub with module docs
15:23:52 <acozine> at least,  this one works: https://docs.ansible.com/ansible/latest/modules/find_module.html#find-module
15:24:20 <samccann> yeah modules should all work. thats all the same bit of code magic. It's the other stuff that isn't rst and isnt modules that have problems if I recall
15:24:32 <acozine> ah, I see
15:24:34 <cbudz> must drop for next meeting
15:24:36 <acozine> yeah, other plugins maybe
15:24:44 <acozine> bye cbudz
15:25:11 <cyberpear> I don't think I had anything more to add.
15:25:25 <samccann> ok thanks cyberpear for popping in with the clarification!
15:25:31 <samccann> #chair cyberpear
15:25:31 <zodbot> Current chairs: acozine cbudz cyberpear samccann
15:25:43 <samccann> cuz you deserve to be furniture for that addition :-)
15:25:46 <acozine> heh
15:26:01 <cyberpear> :P
15:26:08 <acozine> I think we should all pick chair styles
15:26:11 <samccann> Okay anything else in Open Floor before we go on to issues and prs
15:26:18 <acozine> we've only got four minutes
15:26:18 <samccann> i'm totally a reclyner
15:26:30 <samccann> recliner?  whatevah
15:26:45 <acozine> speaking of reclining, I think I need to go lie down
15:26:54 <acozine> I've got a cold or the flu or something
15:27:04 <samccann> go.. shoo
15:27:11 <acozine> and I think I just hit my contribution limit for the morning
15:27:16 <samccann> I'm just gonna pop in some docs stats and call it a day
15:27:26 <acozine> sounds great, thanks samccann
15:27:28 <samccann> #topic Docs Issues and PRs
15:29:21 <samccann> We have 225 open Docs Issues.  That seems to be holding pretty steady, which means we are closing/fixing at about the rate new ones are open
15:29:38 <samccann> Would like to see that number go down tho, so please do go adopt an issue
15:30:23 <samccann> #info we have 225 open Docs issues and 102 open docs PRS
15:30:49 <samccann> So my last call is for folks to review docs PRs  . that number is rising and we want to be able to merge the hard work folks are doing to help with docs.
15:30:53 <samccann> And thats that!
15:30:56 <samccann> #endmeeting