15:01:48 <acozine> #startmeeting Docs Working Group aka DaWGs
15:01:48 <zodbot> Meeting started Tue Jun 25 15:01:48 2019 UTC.
15:01:48 <zodbot> This meeting is logged and archived in a public location.
15:01:48 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:48 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:48 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
15:01:56 <acozine> who's around?
15:02:14 <samccann> \o
15:02:22 <acozine> #chair samccann
15:02:22 <zodbot> Current chairs: acozine samccann
15:03:37 <acozine> andersson007_: felixfontein mrproper ndclt orthanc Pilou Xaroth663 zoredache are you folks up for talking docs today?
15:05:07 <acozine> belfast77: brtknr cyberpear dfed elroncio jhawkesworth madonius shaps theo-o feel free to lurk, but also to participate!
15:05:35 <acozine> (I'm omitting those whom I know to be in time zones where it's the middle of the night)
15:06:06 <acozine> we have no official agenda today, but I'd like to look at one PR for sure, and maybe a few issues
15:06:48 <acozine> oh, and follow up on last week's introduction of the custom 404 page and the version-switcher
15:07:42 <dfed> good morning everyone.
15:07:57 <samccann> morning dfed
15:08:19 <acozine> #topic dfed: good morning!
15:08:27 <acozine> heh
15:08:32 <dfed> lol!
15:08:36 <acozine> that's what I get for getting distracted
15:08:48 <samccann> it's a good topic
15:09:06 <acozine> #topic Quarter of UI/UX Work
15:09:43 <acozine> We've been focusing this quarter on improving the docsite, including the build tools and the look-and-feel
15:10:37 <acozine> The version-switcher and the 404 page have long been on the community wish-list
15:10:49 <acozine> so it's great to see them in use
15:11:18 <samccann> version switcher is in action now - https://docs.ansible.com/ansible/latest/index.html - see top left-hand side
15:11:41 <samccann> and the 404 fun can be seen at - https://docs.ansible.com/ansible/latest/inde.html
15:13:04 <acozine> known remaining work includes removing the extra search facility and adding banners directing folks toward the latest release
15:13:56 <samccann> dfed: one of the debates on the version switcher was - do users understand `latest` vs `devel`
15:14:05 <samccann> dunno if you have an opinion on that?
15:15:39 <acozine> there was also a question about whether the version-switcher should refer to the latest version (whatever it is) by version number or by name
15:16:05 <samccann> yeah basically that question :-)
15:16:10 <dfed> Not in my experience.
15:16:52 <samccann> k thanks!
15:17:01 <dfed> some may, but there will be lots of folks who just want to know latest stable docs because drone work.
15:17:33 <acozine> the challenge for us is - we want to encourage users to land on the `latest` URLs, especially for favorites, links in blog posts, etc., so in future we don't have to maintain a ton of redirects, and so they see the latest updates and features
15:18:26 <acozine> but I can see it would make more sense to list 3 version numbers plus `devel`
15:19:24 <dfed> blog posts get out of date, and many likely will point to oold docs.  It's up for debate if that's a good thing or not.
15:20:23 <dfed> but a blog post on an out of date module may still need to link to old docs/that module. not sure if redirects to latest helps there.  As long as latest notes that something is depricated clearly I guess not
15:20:51 <acozine> yeah, there are good aspects to it - if the features have changed, you don't want folks linking from an old blog post to the new docs if everything works differently now
15:21:04 <dfed> deprecated and wow I need coffee brb.
15:21:13 <acozine> heh
15:21:51 <samccann> so let me experiment and see what I can come up with to have 2.8 in the dropdown, but accept incoming latest links
15:22:14 <acozine> if the dropdown could list `2.8` but point to the `latest` URLs, that would be ideal
15:22:25 <samccann> not sure about that
15:22:33 <acozine> though we'd need to remember to update it on all versions when a new release came out
15:23:00 <cyberpear> `latest (2.8)`?
15:23:05 <samccann> I can easily see `2.8` working and still accepting `latest` but it's harder to replace `2.8` in the url with `latest`..
15:23:11 <samccann> cyberpear: yes
15:23:25 <acozine> ah, I like that
15:23:47 <samccann> but our small survey so far (3 people) all agree that `latest` isn't as well known and could confuse users into thinking it was NOT the stable branch
15:24:02 * acozine heads back to the release checklist to add an item
15:24:13 <samccann> what item?
15:24:29 <samccann> oh update the version changer versions  :-)
15:24:33 <acozine> yep
15:26:09 <samccann> #action samccann to experiment with using `2.8` in the version changer instead of `latest`
15:27:03 <acozine> I really like cyberpear's suggestion that the dropdown show both the word and the version number . . . that teaches people the meaning of the word as they go
15:27:21 <acozine> or the context
15:27:53 <samccann> oh hahah missed the subtley of that response!
15:28:40 <samccann> that might tax my limited javascript skills (since I'd have to have the text and the url in a deeper ...er...array?)
15:28:45 <samccann> but I can try
15:29:08 <acozine> give it a try; I'm sure this group will pitch in if you need help
15:29:14 <acozine> are there other UI/UX improvements we should be looking at?
15:29:15 <samccann> #info try to add `latest(2.8)` to the dropdown
15:29:23 <samccann> the extraneous search
15:29:48 <samccann> #topic removing extra search box
15:29:56 <acozine> yes!
15:30:08 <samccann> This is the search box in the upper left hand corner.  Should be simple to remove it
15:30:48 <samccann> We have the deeper search in the lower-left bottom `site search` which is stronger in terms of internal stats we can gather from searches to help improve the site overall
15:31:22 <acozine> Open issue with some details is: https://github.com/ansible/ansible/issues/45939
15:31:25 <samccann> But we need to figure out how to imrove that `site search` since it currently sprinkles in search results from `2.3` for who knows what reason at the moment
15:32:13 <acozine> I think it would also be good to have the search box appear in the upper left - that is the traditional location (at least, that's where I look for a search box when I use a site I don't know)
15:32:44 <samccann> yeah not sure if I have the skills to move site search up.  how critical is that to getting us down to one search box?
15:33:19 <acozine> I guess if we remove the current upper left box, we'll find out ;-)
15:33:48 <samccann> AAAHAHA
15:33:58 <acozine> I remember when I first came on board, there was discussion about the search facilities, and some folks had strong opinions
15:34:08 <acozine> I do not remember the details though
15:34:52 <samccann> well it also brings up - afaik tower only has search in the lower right, ansible has two searches, and galaxy only has one, in the upper left
15:35:47 <acozine> yes, it would be great if all the docs had a similar design
15:35:53 <samccann> oh and ansible-lint only has one, in the upper left
15:36:24 <samccann> my guess - as more 'sites' were added, they pulled in the easy search (opensearch) as part of the theme, but didn't link into the deep analytics `site search`
15:38:26 <acozine> the `site search` link is for Swiftype, which is a paid service, so our subscription may only cover a certain number of sites/URLs
15:39:56 <acozine> somewhere I have a login for the site, which I believe allows us to optimize . . .
15:42:29 * acozine has looked and come up empty so far . . . will report back for next week
15:43:01 <samccann> heh
15:43:20 <samccann> meanwhile I can ask some folks if they remember any debates on the search options from last year
15:43:30 <acozine> there's one other known issue in flight . . .
15:43:37 <acozine> #topic banners for old versions
15:44:12 <acozine> as part of encouraging folks to upgrade, and also making sure people know when they're looking at outdated pages, we're thinking of two banners
15:44:28 <acozine> one for still-maintained-but-not-latest versions
15:44:42 <acozine> and one for not-maintained-here-be-dragons versions
15:45:17 <samccann> someone also suggested a banner to say devel is the bleeding edge so to speak.
15:45:27 <samccann> aka everything but latest gets a banner
15:45:36 <acozine> ah, that's a good idea, and that one would require zero maintenance
15:45:51 <samccann> heh... fingers crossed
15:47:10 <acozine> we don't have an issue for the banners - would that be helpful?
15:47:17 <samccann> sure
15:47:31 <acozine> cool, I'll create one
15:51:58 <acozine> https://github.com/ansible/ansible/issues/58346
15:52:07 <acozine> yikes, we're nearly out of time
15:52:19 <acozine> #topic open floor
15:52:37 <acozine> does anyone have other UI/UX concerns or ideas? things we should add to the queue?
15:52:48 <acozine> or other concerns/ideas to bring up?
15:53:28 <samccann> as a 'background' task, I want to pull in as much of that latest rtd_sphinx_theme as we can. just so it's easier to keep up todate with changes etc.
15:53:44 <samccann> I don't know that it will have visible changes. TBD on that
15:53:49 <acozine> samccann: sounds great
15:54:27 <acozine> maintenance is easier when it's done steadily, and if we can get caught up, that would help a lot
15:55:40 <acozine> I'd like to give two shoutouts this week
15:56:44 <samccann> shout it out!
15:56:49 <acozine> one to felixfontein for fixing the pygments lexers in Ansible, for opening a PR to pygments, and for following up when that PR got merged
15:57:09 <samccann> felixfontein++
15:57:28 <acozine> and one to GitHub user anis016 for picking up several `easyfix` issues and fixing them
15:57:47 <samccann> wootwoot!  anis016++
15:58:47 <acozine> I'm hoping he will join us here
15:59:12 <acozine> (or maybe he already has, but his nick is different here . . . )
15:59:33 <acozine> IRC vs GitHub has tripped me up many a time
16:00:44 <acozine> also thanks to ndclt who made a first contribution this week!
16:01:23 <acozine> thanks, folks - that's it for today . . . see you next week
16:01:39 <acozine> as always, agenda items welcome at https://github.com/ansible/community/issues/389
16:01:43 <acozine> #endmeeting