15:31:30 #startmeeting Documentation Working Group 15:31:30 Meeting started Tue Jan 29 15:31:30 2019 UTC. 15:31:30 This meeting is logged and archived in a public location. 15:31:30 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:31:30 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:31:30 The meeting name has been set to 'documentation_working_group' 15:31:41 who's around? 15:33:22 heh, am I here all by myself? 15:33:42 o/ 15:33:48 hallo! 15:33:54 #chair samccann 15:33:54 Current chairs: acozine samccann 15:34:43 i just put out some helloooos in the other channels to remind folks of our DaWG fun 15:34:51 We have four items on the agenda 15:35:52 * gundalow waves 15:35:58 #chair gundalow 15:35:58 Current chairs: acozine gundalow samccann 15:37:34 agenda items listed here: https://github.com/ansible/community/issues/389#issuecomment-458179675 15:37:49 first item is identifying PRs that need backporting 15:38:18 #topic which docs PRs should be backported to `stable-2.7` 15:38:28 o/ 15:38:36 #chair dag 15:38:36 Current chairs: acozine dag gundalow samccann 15:39:00 * gundalow knows he said many weeks (month(s)) ago he'd backport docsite/community into `stable-2.7` though hasn't gotten around to that yet 15:39:00 hey dag! 15:39:09 'ello everyone 15:39:17 #chair alongchamps 15:39:17 Current chairs: acozine alongchamps dag gundalow samccann 15:39:26 welcome alongchamps: 15:39:52 gundalow: do you have the PR# for the docsite/community stuff handy? 15:40:35 yesterday I backported 5 "mechanical" PRs, including one I probably shouldn't have 15:40:43 acozine: it's many PRs. I might just bulk copy stuff 15:40:59 acozine: though TBH I'd like for their to only be one version of `/community` 15:41:03 acozine: I don't know, I wasn't sure if we wanted to do this :) 15:41:10 gundalow: that sounds fine, especially if all the changes are to the same few files 15:41:49 acozine: ideally we want everything docs-related to be backported, but all the effort is not as important as giving users the ability to look at the latest documentation 15:41:55 dag: yeah, I published `stable-2.7` to the test site, and without the metadata for type, it looks a little weird 15:42:05 if we only want one version of community, can we just add links from the stable branches to devel, with a note to say this will bring you to devel? 15:43:03 for those who don't know what dag and I are talking about, the PR I backported was https://github.com/ansible/ansible/pull/49966 - backport for this was https://github.com/ansible/ansible/pull/51394 15:43:06 samccann: I prefer either [2.5][2.6][2.7][devel] or a dropdown 15:43:47 and it doesn't have to be too smart, as long as we have a 404 error page that offers a friendly message and ability to search 15:44:04 and here's what it looks like: http://docs.testing.ansible.com/ansible/latest/modules/omapi_host_module.html#omapi-host-module 15:44:21 hum, got a dumb 404 page at the moment https://docs.ansible.com/ansible/devel/community/fdsa 15:44:35 gundalow: where's the .html on that? 15:45:10 hm, that doesn't work either 15:46:14 gundalow: what page is that supposed to be? I'm looking at https://github.com/ansible/ansible/tree/devel/docs/docsite/rst/community and I don't see anything similar 15:46:25 but we digress . . . 15:46:28 #topic 15:46:41 oops, that wasn't what I wanted to do 15:47:04 acozine: it doesn't (and never) existed, was answering dag's point of `as long as we have a 404 error page that offers a friendly message and ability to search` 15:47:13 ah, i see 15:47:33 I'm a little lost 15:47:38 #topic backporting 15:47:47 gundalow: the 404 page is problematic IMO easy to fix 15:47:56 if I'm following this, we started by asking which PRs to backport 15:48:12 gundalow: and automatic pointers to other versions is not hard to add either 15:48:25 ok so the real topic is some 404 page issue? does this relate to gundalow's community page request for backport? 15:48:27 then we started talking about maybe having some non-versioned sections of the docs 15:48:28 but we have been discussing this for more than 2 years, time for some action :) 15:49:06 sorry if I went off topic 15:49:10 acozine: sorry, my point was that backporting docs PRs is less important than giving users the ability to find the latest docs 15:49:17 dag: +1 15:49:27 what's your thoughts on how to make it easier? 15:49:38 acozine: and backporting docs is a lot of work and only fixes 2.7 15:49:50 samccann: yes, the two are related, because the proposal on the table is: if we only maintain `devel` for some content, then we need to allow users to navigate between the versioned docs and the non-versioned docs 15:50:03 I'd *really* like for `/community` and `/dev_guide` to have big red banners on the top if you are not on the `/devel` version 15:50:21 gundalow: I think they should only offer the latest, no banners needed 15:50:42 gundalow: You can fix this easily with some httpd config tweaks 15:51:17 dag: if we do that, how do we make it easy for users to navigate back to versioned docs and understand what version of, say, the module docs they are looking at? 15:51:20 especially if you have these [2.5][2.6][2.7][devel] links at the top, it would be obvious what you see 15:51:34 latest only could also help avoid a lot of incomplete doc pages 15:51:38 back button will still work 15:52:03 breadcrumbs with version in it could help as well 15:52:30 +1 to better breadcrumbs 15:52:31 (help in making clear where you are) 15:52:39 ^^^ that's my main concern 15:53:19 so the root 'breadcrumb' could be "2.7 > ..." instead of "Docs > ..." 15:53:26 that people will look at module docs for 2.7, then look at a community page, then look at another module and not understand that they are now looking at `devel` 15:53:34 or "Docs > 2.7 > ..." 15:53:40 acozine +1 15:53:51 even a breadcrumb won't aleviate that confusion 15:54:07 acozine: not with the current page design 15:54:08 hence banner/breadcrumbs rather than silent redirect 15:54:23 there's a conflict in there between `latest` for ansible itself (which is the current stable release) and the most recent docs (which are the devel branch0 15:54:30 which is why I suggested we REPLACE the 2.7 community with a link (preferably one that opens a new browser or tab) to devel 15:54:35 Google is now setting `/latest` as the preferred page, so should be getting better 15:54:37 the current page design does not 1. make clear what version you have 2. make clear there are multiple versions 15:54:47 dag: +1 15:54:51 dag +1 agreed 15:54:52 dag: agreed, the current design is terrible 15:54:57 gundalow: still not true for a lot of pages unfortunately, I don't know why 15:54:58 that's one problem 15:55:17 keeping /comunity and /dev guide as only the devel version is a separate (related) problem imo 15:55:25 dag: ping me some example searches/URLs and I can take a look at the webstats 15:56:30 dag: what does your suggested redesign look like? 15:56:34 #topic How do we add version navigation aids to docs.ansible.com 15:56:35 gundalow: I am trying to find something, but I think Google has come around ;-) 15:56:50 ah, that's awesome! 15:57:00 so we have made progress on that front 15:57:21 dag: It went live end of Dec, from looking at the stats it's taken a few weeks for the trends to change 15:57:50 #info currently very difficult to navigate to a different version from /latest 15:58:06 acozine: I would add either a pull-down or [2.5][2.6][2.7][devel] links at the left-top, add the version in the breadcrumbs, a better 404 page that offers help navigating and probably a better indication in man-pages what version you are at 15:58:20 #info a related issue - the community and dev guide should really only be the /devel version that users access 15:58:40 samccann: the releases/support pages as well 15:58:50 (not sure where they live) 15:59:02 releases/support is in the appendix 15:59:08 dag: as in show only the devel versions of those regardless of what release the user is looking at? 15:59:43 samccann: yes, either by replacing that content (preferred), proxying (possible) or redirecting (probably not a good idea) 15:59:59 or just a link to the devel version? 16:00:19 #info this 'show only devel version' of docs content applied to releases/support pages in appendix as well 16:00:24 I realize that for maybe v2.5 the structure was not identical, but since everybody these days ends up in latest, maybe that's no longer a real concern 16:00:45 and we should focus on making sure "latest" has the "devel" content 16:00:53 dag: +1 16:01:05 dag: when you say "replacing that content" - do you mean we would *publish* the `devel` version of certain pages to all versions of docs.ansible.com? 16:01:18 that's an approach I hadn't thought of 16:01:34 acozine: you could backport those, but I think it's probably easier by replacing it before building 16:01:48 it will depend on how similar the build instructions and other stuff is 16:01:57 but if we only go one release back (latest) it is actually doable 16:02:11 I think `latest` is the most important one to do 16:02:25 and if people on search engines end up on latest, my main concerns are gone 16:02:46 (for older we could get away with a red banner/link to click through) 16:03:04 but I would avoid any red banners for latest ;-) 16:03:56 I like this approach, though I don't understand the details yet 16:04:02 +1 I like the idea of adding a red banner to the older (still supported) pages 16:04:07 in any case, now that people end up on latest, we still need to offer them the option to look at [2.5][2.6][2.7][devel] (at least this will be a very deliberate choice, so that's good) 16:04:51 there's currently a link to 'documentation archive' but it doesn't seem to work for me 16:05:19 samccann: that link never gets you to the exact same page you were visiting, so it's problematic 16:05:23 I can write a ticket for the "better 404" part of the work 16:05:31 acozine: +1 16:06:09 and possibly for the "add a red banner to outdated versions" (currently 2.5 and 2.6, but preferably engineered to adapt as we release new versions) 16:06:10 if we modify the breadcrumbs and add [2.5][2.6][2.7][devel] this needs to happen on all branches 16:06:36 yeah, preferably this is dynamically generated 16:06:39 * gundalow doesn't want us to have to maintain looks from 2.7 to older versions. 16:06:40 (javascript) 16:07:01 gundalow: for this kind of groundwork you can't do without IMO 16:07:10 not if you interlink like we do 16:07:21 hmm... maybe we can use those website stats to see 16:07:42 preferably this is also dynamically generated so that interlinks are no longer shown if the release is unsupported 16:07:42 the breadcrumbs and the "some content from `devel` is published to both `latest` and `devel`", I'm not as clear on 16:07:43 are we still getting enough hits on 2.5/2.6 since the search brings folks to latest now? 16:08:27 samccann: if you have an interface to go from 2.7 to 2.5, the same interface should be there to bring you back IMO 16:08:30 * gundalow is looking at website hits, not seeing much on 2.5 since mid dec 16:09:10 good ! 16:09:31 dag: what I'm saying is, let's get 2.7, devel working with correct navigation/breadrumbs. then based on website stats, we decide if we need this going back to 2.6 or not. And if someone is clever, this solution works automagically for future supported versions. 16:09:43 * samccann has no magic but hoping someone here does 16:10:34 * bcoca checks pixie dust bag 16:11:45 okay, what are our action items? 16:12:18 #action acozine to create ticket for a better 404 page for docs.ansible.com, with links to various versions 16:12:50 latest/playbooks_intro 10,000 hits/day 16:12:50 2.6/playbooks_intro 50 hits/day 16:13:02 hooray! 16:13:11 wow! hope that page is accurate :-) 16:13:21 lies, damn lies and website stats 16:14:54 samccann: sure, that is fine 16:15:07 so I think we still wanted the red banner on 2.5/2.6 pages that we feel should only really be using devel? 16:15:14 (in terms of action items) 16:16:26 #action acozine to start ticket about content that should be unified across at least `devel` and `latest`, with the goal of doing less backporting and getting better navigation for users 16:16:45 ^^^ that can include the red banner for older versions 16:16:56 and/or a dropdown for changing versions 16:17:35 I think a red banner might be easier to implement as part of an iterative process 16:17:39 * dag would prefer no red banners, but the right content only (2.5 and 2.6 should offer the content ) 16:17:47 but a red banner might be a temporary measure 16:18:14 dag: yeah, I think the key to action is to make incremental improvements 16:18:21 sure 16:18:34 then we have something specific to argue about ;) 16:18:40 maybe a yellow warning banner that it's >1 release old? or some info pane that can't be missed 16:19:38 agreed alongchamps - something that makes it obvious you may not be on the page you really should be on. 16:19:46 alongchamps: nice ideas - maybe everyone could add mockups to the issue once it's live 16:20:47 we've got ten minutes left 16:20:58 our other agenda items are: 16:21:46 2. the printing issue - I think felixfontein's ideas for that are actionable - anyone who wants to take a stab at a PR to fix the issue is welcome to jump in! 16:22:00 issue is here: https://github.com/ansible/ansible/issues/40371 16:22:26 3. how often should we publish docs for `latest` and the older verions 16:22:39 that's really part of the discussion we've been having 16:22:49 about backporting and versions and so on 16:22:56 and finally . . . 16:23:15 4. crosslinking in the User Guide 16:23:22 hm, I'm forgetting the IRC log 16:23:40 #topic issue 40371 - can't print long docs pages 16:23:57 this issue is actionable now, thanks to felixfontein 16:24:35 gundalow: what's the command for "make this thing stand out in the minutes"? 16:24:41 #link https://github.com/ansible/ansible/issues/40371 16:24:47 samccann: thanks! 16:25:13 acozine: #info 16:25:28 do we want to try and get a quick consensus on how often to publish `latest`? 16:25:42 (not to topic-hop or anything) 16:25:54 #topic how often to publish `latest` 16:26:35 I'mma put my starting bid in for every other Tuesday 16:26:40 I think if we take the approach we've been discussing, where we're publishing the `devel` docs to both `devel` and `latest` for a lot of stuff, 16:26:42 since we aren't backporting that regularly 16:26:51 then we can publish in synch with the minor releases 16:27:06 are those every 2 weeks? 16:27:13 I think so, yeah 16:27:20 on Thursdays, I think 16:27:45 is there a drawback to pushing frequently ? 16:28:25 dag: it's not automated, because there aren't so many changes 16:28:46 but it is automated for devel, so the question is why isn't it automated ? 16:28:52 is there a risk to it ? 16:29:01 if so, can we avoid that risk ? 16:29:05 I simply don't know 16:29:08 less risk now than there used to be, since we have CI coverage 16:29:12 for the docs build 16:29:18 and also, how often do we have `latest` changes? 16:29:44 good question, but if there is no drawback, there is also no reason to do it daily 16:29:56 I think the downside of automating would be the burden on internal resources (Jenkins, etc.) 16:29:58 (if it were to be automated) 16:30:12 also, we'd have to check daily to be sure nothing died. 16:30:34 I'd rather limit that to weekly at most 16:30:42 ok, so we always build from a clean slate, which means it is quite heavy, why don't we build from an existing tree ? 16:30:55 samccann: so there is a risk of something dying ? 16:31:13 proposal: automate a weekly build to `latest` on Thursday nights to coincide with our usual release schedule 16:31:16 I would think we only replace (move a symlink?) if the builds succeeded 16:31:19 well I know we have a jenkins build for devel and I'd say based on limited past experience, it dies once a quarter 16:31:35 ok 16:31:38 IF that death means docs.ansible.com is also dead, then that worries me 16:31:52 that would be badly designed if it were :-) 16:32:02 if it dies, it shouldn't be published... 16:32:19 yeah I've seen the jenkins failure, but it's usually resolved before I get the chance to see what it meant for docs.ansible.com 16:32:38 that's why moving a symlink or something like that also helps in reverting to a previous build, or comparing builds 16:32:52 BTW Someone opened an issue for reproducible builds (related to docs) 16:33:05 so distribution people are looking into that ;-) 16:33:31 my nickel (based purely on paranoia) is that if it's going to `latest` docs, a human should be verifying it after it publishes 16:33:38 for me once a week is fine if we are not confident, or there are other possible risks 16:33:52 samccann: verifying, like in, reading everything ? ;-) 16:34:00 scanning a few pages 16:34:17 that would greatly improve our offering, if it was to be proofread every week :-D 16:34:18 so take 15 minutes after it publishes to poke around 16:34:23 AAAHAHAHA 16:34:31 dag: spot-checking a few modules, hitting the main index pages 16:34:41 dag: I nominate you as proofreader! 16:34:52 I would automate that with an Ansible module 16:35:13 it's automation all the way down, eh? 16:35:26 hey, we're over time for the meeting 16:35:39 samccann: how do you feel about the weekly build to `latest`? 16:35:51 shall we try it for, say, a quarter and see how it works out? 16:36:08 I'm fine with it so long as one of us looks at it after (so it needs to happen during 'office hours' so to speak) 16:36:28 so automate, and we have our own calendar remidner to check it out after 16:36:32 okay, let's talk offline about what time works best 16:36:50 +1 16:36:53 #info agreed we will try a weekly automated build of the `latest` docs 16:37:17 so, we don't have time for the User Guide discussion in the official meeting 16:37:37 #agreed weekly build automated for `latest` docs with quick human verification right after 16:37:57 sigh . . . someday I will learn those IRC commands 16:38:00 thanks samccann 16:38:18 i only remembered cuz you used the word in that sentence :-) 16:38:44 okay, thanks everybody! that's the end of the official DaWGs meeting this week 16:38:51 Thanks :) 16:39:13 discussion welcome in this channel any time! 16:39:17 #endmeeting