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