15:01:02 <acozine> #startmeeting Ansible Documentation Working Group
15:01:02 <zodbot> Meeting started Tue May 21 15:01:02 2019 UTC.
15:01:02 <zodbot> This meeting is logged and archived in a public location.
15:01:02 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:01:02 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:01:02 <zodbot> The meeting name has been set to 'ansible_documentation_working_group'
15:01:08 <acozine> who's around today?
15:01:14 <felixfontein> me not really, sorry :/
15:01:23 * samccann waves
15:01:33 <acozine> felixfontein: np, thanks for the reviews and backports this week
15:01:39 <acozine> #chair samccann
15:01:39 <zodbot> Current chairs: acozine samccann
15:02:50 <acozine> anybody else?
15:03:30 <acozine> alongchamps andersson007_ decentral1se Pilou Xaroth zoredache ?
15:03:43 <alongchamps> not today, on the phone with VMware support
15:04:02 <acozine> alongchamps: ah, bummer - hope you get the answers you need
15:04:21 <acozine> I'll post a quick update to start with
15:05:37 <acozine> 2.8.0 was released last week, and the `latest` docs now point to the stable-2.8 branch
15:05:57 <samccann> wooot!!
15:06:16 <acozine> if you've got a docs change that went into `devel` in the last month or so, and you don't see it in the `latest` docs, feel free to open a backport PR
15:07:11 <samccann> #info Ansible 2.8.0 released last week. If you have a doc PR that went into devel and you don't see it on latest, open a backport pr
15:07:57 <acozine> we are preparing to integrate the version-changer, so we're working to make sure the maintained older versions (2.6 and 2.7) have broadly similar navigation and display as the `latest` docs
15:08:00 <samccann> see #link https://docs.ansible.com/ansible/latest/community/development_process.html#backporting-merged-prs
15:08:16 <acozine> samccann: thanks for posting the link to the backport instructions!
15:10:22 <samccann> sometimes I remember how irc works :-)
15:10:41 <acozine> along with the better-404-page issue, we've got another web-dev issue open:
15:10:51 * alongchamps done with support so I'm here
15:10:57 <acozine> https://github.com/ansible/ansible/issues/56619 was opened by mrproper, who is on the road today
15:11:04 <acozine> #chair alongchamps
15:11:04 <zodbot> Current chairs: acozine alongchamps samccann
15:11:10 <acozine> alongchamps: w00t
15:12:40 <acozine> I'd like to address as many docs user-experience issues as we can in the next quarter
15:13:09 <samccann> #info hoping to focus the next 3 months on addressing docs user-experience issues
15:13:22 <samccann> #topic docs user experience issues
15:13:37 <acozine> known UX issues include:
15:13:43 <samccann> newest related issue - #link https://github.com/ansible/ansible/issues/56619
15:13:56 <acozine> make docsite more responsive by allowing users to toggle the left nav
15:14:09 <acozine> (that's 56619)
15:14:12 <samccann> is there a way we can label these user experience issues?
15:14:43 <acozine> hmmm
15:14:45 <samccann> docsite would be an obvious label but that's already used for prs created via the docsite 'edit in github' button
15:14:45 <acozine> I don't know
15:15:12 <samccann> just thinking it would be easier to batch them up.  Or maybe instead we just create a user-experience column on the core project board and add them there?
15:16:09 <samccann> this is the project board i'm thinking about - https://github.com/ansible/ansible/projects/27  or we create a website project board to keep this work separate?
15:16:28 <acozine> it looks like we have two separate labels: `docsite_pr` and `docsite`
15:16:34 <samccann> oooOOOoo
15:16:45 <acozine> i doubt we've been consistent with them
15:16:58 <acozine> but I don't think either one is added by the bot
15:18:21 <samccann> um I think both are actually
15:18:32 <acozine> the `docsite_pr` label is supposed to be for PRs "created from documentation using the `Edit on GitHub` link."
15:18:43 <acozine> samccann: oh, are they?
15:18:43 <samccann> this pr has 'docsite' label added by ansibot at the end https://github.com/ansible/ansible/pull/54349
15:19:28 <acozine> you're right
15:20:15 <acozine> the `docsite` label is for any issue or PR that "relates to the documentation website."
15:20:29 <acozine> which I guess is . . . all docs PRs and issues?
15:21:00 <samccann> yeah not sure
15:21:30 <samccann> anyway, let's define 'user experience' first
15:22:02 <acozine> I'd say anything that makes it easier for users to find the documentation they are looking for, on any device
15:22:14 <samccann> is this what happens on the website for docs.ansible.com? (like the version changer, better 404, hidable navigation, better breadcrumbs etc)?
15:22:32 <acozine> yeah, that would be my suggested definition
15:22:44 <acozine> what am I forgetting/overlooking?
15:23:04 <alongchamps> this all sounds good to me, anything that would help end-users on the site would probably go in to UX improvements
15:23:09 <samccann> I tend to jump to 'what's the fix' and these are all sphinx-theme/html etc related
15:23:35 <samccann> yes, site changes.  vs user experience issues like that [u!config] fix
15:24:02 <alongchamps> so then 'ux improvements' and 'ux issues' could both be tags
15:25:15 <acozine> alongchamps: I'd suggest we use one tag for both the issues and the fixes - that makes it easier to track things
15:25:16 <samccann> do we know who could approve new labels? or do we want a project board for this?  Because the labels would be manually added anyway, so could just as easily add it to a project vs add a label when the issue is created
15:25:38 <acozine> I think I can make new labels, but I hesitate to do it unless we're really sure it's necessary
15:25:43 <samccann> tho labels would help us easily see 'we have xxx ux issues open' etc
15:25:48 <acozine> we've got so many labels already
15:26:01 <acozine> agreed, labels are incredibly useful
15:26:09 <samccann> heh yeah I just looked at  all the labels to see if anything could be used for this !
15:26:27 <acozine> what's the downside of using `docsite` for these?
15:26:31 <acozine> not granular enough?
15:26:41 <samccann> well how about we start with -triage the docs issues and add appropriate ux ones to a new docsite project board (can we add a new project board)?
15:27:13 <acozine> samccann: I can definitely add project boards
15:27:21 <acozine> alongchamps: can you see the project boards?
15:27:45 <acozine> like https://github.com/ansible/ansible/projects/27
15:28:06 <acozine> I don't think they're private, but I'd like to confirm before we go too far down that road
15:30:55 <acozine> hm, I think alongchamps went back down the vmware rabbithole
15:31:10 <alongchamps> yup I'm back
15:31:30 <acozine> heh, can you see the project board linked above?
15:31:37 <alongchamps> yes I can see the project board
15:32:08 <acozine> awesome - what do you think of a Docs UX project board, either with or instead of a label?
15:32:30 <acozine> obvious advantages or obvious drawbacks?
15:33:01 <alongchamps> I think a ux-related label would be helpful since after all that's what labels are for
15:33:13 <samccann> fwiw we can search all issues by project board as well
15:34:08 <acozine> here are all the issues and PRs that currently have the `docsite`label:
15:34:08 <samccann> in terms of tracking/prioritizing, I can see the board being helpful vs just a label.. but from the user creating/triaging issues for ux - I think folks are used to adding labels.
15:34:10 <acozine> https://github.com/ansible/ansible/labels/docsite
15:34:26 <alongchamps> so then everything would just be found under 'docs' then ?
15:34:41 <alongchamps> oops I was a few messages behind (thanks auto-scroll)
15:35:06 <acozine> alongchamps: we have three labels: `docs` and `docsite` and `docsite_pr`
15:35:20 <acozine> I think we've been a bit muddled in how we use them
15:35:34 <alongchamps> I was just thinking, what's the definition of when to use them
15:35:38 <acozine> I like `docsite_pr` for PRs that came from "Edit on GitHub"
15:35:44 <alongchamps> +1
15:35:51 <samccann> +1
15:35:58 <alongchamps> then could we combine docs and docsite? not sure the difference
15:36:03 <acozine> that's really helpful, esp. when the PR needs a little help
15:36:10 <samccann> I'd love to take `docsite` over for just docsite ux issues/prs
15:36:16 <alongchamps> unless one was for the site layout/features (e.g. 404 page improvements)
15:36:24 <samccann> but ansibot is using it... and I haven't a clue how to change ansibot behavior
15:36:36 <acozine> +1 to using `docsite` for docs UX only
15:36:54 <acozine> and `docs` for writing stuff only
15:37:04 <alongchamps> +1 and +1 for both of those
15:37:09 <acozine> awesome
15:37:20 <acozine> okay, so we need to get Ansibot to understand that usage
15:37:31 <alongchamps> who mains it?
15:37:45 <samccann> and remove the existing `docsite` labels (30+)
15:37:46 <alongchamps> s/mains/maintains
15:37:49 <acozine> my guess is that we want `docs` and `docsite_pr` to be automated, and save `docsite` for human addition?
15:37:58 <samccann> +1
15:38:04 <alongchamps> +1
15:38:14 <acozine> alongchamps: I think jctanner maintains ansibot; I can investigate
15:39:11 <samccann> #agreed we want `docs` and `docsite_pr` to be automated, and save `docsite` for human addition
15:39:41 <samccann> #action acozine to find out how to change ansibot so it no longer auto-labels with `docsite`
15:39:42 <acozine> #agreed the `docsite` label should be used for docs UX/UI issues and PRs
15:39:57 <acozine> cool!
15:39:57 <samccann> we're all so agreeable today!  :-)
15:40:04 <alongchamps> +1
15:40:07 <alongchamps> :)
15:40:30 <acozine> we're happy DaWGs
15:41:11 <acozine> okay, I know next steps for the coming week and even some things to put on the agenda for next week
15:41:13 <acozine> that's awesome
15:41:20 <acozine> #topic open floor
15:41:22 <samccann> \o/
15:41:38 <acozine> alongchamps: anything on your mind? got any PRs to review or concerns to air?
15:41:55 <alongchamps> Nothing from me
15:42:23 <samccann> I've just added a new/easy pr if you want to look - https://github.com/ansible/ansible/pull/56722
15:42:43 <samccann> otherwise not much else to chat about here
15:43:20 <samccann> oh!  I do have a question - assuming I get the version changer working, should I hop on the 404 fix next since it's gated by that fix?
15:44:04 <acozine> samccann: that would be great
15:44:17 <samccann> k
15:44:25 <acozine> 56722 looks good - I like leveraging existing content
15:44:51 <acozine> it means less maintenance overall, and more buy-in from other stakeholders
15:44:59 <samccann> yep
15:46:19 <acozine> oh, once we've got Ansibot doing what we want it to, we should update the contributing-to-docs page to tell people what the labels mean
15:46:49 <acozine> make it easier for folks to find issues they are comfortable working on
15:47:10 <acozine> I think we can wrap up a little early today
15:47:28 <acozine> thanks alongchamps samccann for a great, and very agreeable WG meeting!
15:47:29 <samccann> sounds good
15:48:13 <acozine> #endmeeting