16:01:26 <acozine> #startmeeting Docs Working Group aka DaWGs
16:01:26 <zodbot> Meeting started Tue Feb  2 16:01:26 2021 UTC.
16:01:26 <zodbot> This meeting is logged and archived in a public location.
16:01:26 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:01:26 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:26 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
16:01:38 <acozine> #topic opening chatter
16:01:49 <acozine> #chair lmodemal samccann
16:01:49 <zodbot> Current chairs: acozine lmodemal samccann
16:01:59 <acozine> sommersoft: welcome!
16:02:13 <sommersoft> ty ty
16:02:44 <acozine> usually anyone who is actively present (reading posts as the meeting goes) gets to be a "chair" (aka gets "turned into furniture")
16:03:07 <abadger1999> Good morning
16:03:10 <felixfontein> I'm partially around
16:03:13 <acozine> it's no big deal, and you can always unchair yourself if necessary
16:03:17 * dericcrago waves
16:03:22 <acozine> #chair abadger1999 felixfontein sommersoft dericcrago
16:03:22 <zodbot> Current chairs: abadger1999 acozine dericcrago felixfontein lmodemal samccann sommersoft
16:03:31 <acozine> good morning/afternoon/evening everybody!
16:04:09 <lmodemal> Happy Tuesday :)
16:04:49 <acozine> who else is around? dmsimard alongchamps andersson007_ bcoca briantist cyberpear gwmngilfen madonius mrproper tadeboro tributarian zbr you folks talking docs today?
16:04:59 <gwmngilfen> o/
16:05:17 <briantist> around sporadically :)
16:05:36 <acozine> I haven't groomed the agenda, so some topics may be "surprises"
16:05:52 <acozine> #chair gwmngilfen briantist
16:05:52 <zodbot> Current chairs: abadger1999 acozine briantist dericcrago felixfontein gwmngilfen lmodemal samccann sommersoft
16:06:25 <alongchamps> I am not around today
16:06:30 <acozine> official agenda is https://github.com/ansible/community/issues/579#issuecomment-767699570
16:06:40 <acozine> alongchamps: enjoy whatever you get up to today!
16:07:18 <acozine> all right, let's get started
16:07:44 <acozine> #topic Index pages for the Core/Package Docsite Split
16:08:46 <acozine> samccann has been working on getting one source repo to print two docsites, one for the Ansible package and one for Ansible Core (with no collections)
16:09:04 <acozine> This allows the version numbers to diverge - Ansible 3.0 vs. Ansible Core 2.11
16:09:16 <acozine> final sticking point was the table of contents
16:09:18 <acozine> https://hackmd.io/mvjYig49R5SQbNHzsd5jfQ?view#Two-Approaches-to-Split-Docs
16:09:24 <acozine> samccann: you want to lead the discussion from here?
16:09:29 <samccann> Sure
16:10:20 <samccann> so if you scan that doc - there are two options for how to do this.  Option 1 - use a separate ansible_index.rst file. This is fairly straightforward but has the need for a redirect to get an index.html for the server
16:11:03 <samccann> Option 2 - Uses the sphinx `..only::` directive and `-t <tag>` to conditionally include or exclude content
16:12:00 <samccann> Option 2 has the benefit of not needing a redirect as it reused the existing index.rst file.  It has the drawback of the `..only::` directive is meant for including/excluding text, not necessarily other things.
16:12:36 <felixfontein> can't you have two different index.rst files, say index_ansible.rst and index_ansible_core.rst, and during docs build copy one to index.html and delete the other?
16:12:41 <samccann> So it's touchy about where it works and doesn't work. It doesn't seem to work well in the index.rst file directly with the complex `..toctree`
16:12:48 <felixfontein> then you need neither a redirect nor `..only::`
16:12:58 <acozine> for new folks, the underlying problem is that some of the content in the ansible/ansible/docs/docsite/rst/ folder is only relevant to the package, not to stand-alone Core - these are mostly legacy pages like the Scenario Guides and the Network content
16:13:13 <samccann> felixfontein: 'someone' probably could do that yeah... it's beyond my limited coding skillset
16:13:34 <samccann> hmm... now that I think out loud, a certain badger showed me how to simlink
16:13:56 <samccann> maybe I can simlink the correct foo _index into index.rst during build time.  That would eliminate the need for a redirect
16:14:08 <acozine> that would be a clean solution
16:14:16 <abadger1999> <nod>  Yeah, I like that idea.
16:14:33 <samccann> #action samccann to do a build time simlink from foo_index.rst to index.rst for the 2 index option to eliminate the need for a redirect
16:14:36 <abadger1999> And I can help out with writing the Makefile rule to symlink if you write the two files
16:15:05 <samccann> abadger1999 - I still have the PR you did that to before. pretty sure I can copy/learn from that but I'll ping you if I hit a snag, thanks!
16:15:32 <abadger1999> Cool :-)
16:15:37 <acozine> \o/
16:15:49 <samccann> so I think we are fairly well agreed that the 2-index w simlink is the preferred approach? can we call that an agreed or do we vote?
16:16:07 <lmodemal> sounds good to me.
16:16:23 <acozine> let's vote, it will demonstrate to our new attendee how voting works
16:16:59 <acozine> VOTE: +1 if you prefer the 2-index-pages-with-simlink solution, -1 if you prefer some other solution
16:17:01 <acozine> #chair
16:17:01 <zodbot> Current chairs: abadger1999 acozine briantist dericcrago felixfontein gwmngilfen lmodemal samccann sommersoft
16:17:05 <acozine> +1
16:17:07 <samccann> +1
16:17:14 <lmodemal> +1
16:18:22 <samccann> (as an aside - the reason we try to vote vs assume we all agree... sometimes with just a couple of us texting back and forth, it can seem like agreement, but once people are asked to specifically vote - it becomes clearer if there is agreement, or if there are other ideas, some hesitation etc)
16:19:26 <acozine> also, sometimes people get distracted as the discussion goes on . . . or disappear entirely because something came up at work/home  ;-)
16:19:28 <sommersoft> i feel the need to abstain. :D
16:19:38 <acozine> sommersoft: yep, that's an option too
16:19:39 <samccann> oh yeah that's also very valid
16:19:46 <felixfontein> +1
16:19:51 <felixfontein> (sorry, distracted :) )
16:20:04 <acozine> heh, case in point ^^^
16:20:10 <felixfontein> hehe :)
16:20:18 <abadger1999> +1
16:20:19 <felixfontein> I didn't do it intentionally ;)
16:20:34 <sommersoft> however, i will note that `exclude_patterns` can have an effect during sphinx build if rst files reference what has been excluded (whether desired or not).
16:21:15 <acozine> oh, good point sommersoft, this may break some internal links on the Core site
16:21:19 <samccann> sommersoft - quite true.. This approach makes liberal use of exclude but ansible sanity tests make sure we don't allow any warnings etc
16:21:49 <sommersoft> (i'm still learning the intricacies of ansible-docs)
16:21:51 <samccann> as for internal links - good point.  I'll followup with the badger fellah (trying not to ping him) but I think intersphinx covers that
16:22:16 <acozine> okay, of 9 chairs, we have 5 votes in favor and one abstention . . . so we'll go with the two-index-pages-with-symlinks solution
16:22:18 <samccann> the tricky point will be - with intersphinx hop someone over to the alternate docsite
16:22:51 <acozine> we should do a quick audit of internal links to the excluded pages
16:22:58 <samccann> #action samccann to see where intersphinx sends me on each site (aka potentially popping to the wrong site)
16:23:42 <abadger1999> It's fine to ping me ;-)
16:23:45 <acozine> anything else on the Core/Package docsite split for today? index pages or other concerns about the split?
16:23:54 <samccann> #action audit of internal links to the excluded pages
16:24:08 <acozine> samccann: you can assign that one to me
16:24:14 <samccann> #undo
16:24:14 <zodbot> Removing item from minutes: ACTION by samccann at 16:23:54 : audit of internal links to the excluded pages
16:24:34 <samccann> #action acoine - to audit internal links to the excluded pages
16:24:35 <samccann> thanks
16:25:08 <acozine> typo?
16:25:22 <acozine> #undo
16:25:22 <zodbot> Removing item from minutes: ACTION by samccann at 16:24:34 : acoine - to audit internal links to the excluded pages
16:25:32 <acozine> #action acozine to audit internal links to excluded pages on Core site
16:25:46 <acozine> otherwise I'll CTRL-f and think I'm off the hook ;-)
16:25:48 <samccann> The only other item will be to work with abadger1999 on how this will work with the Ansible package he's currently building. I can't recall the details, but we'll need to backport to stable-2.10 and then 'adjust' as needed to be able to continue to publish Ansible 2.10, plus Ansible 3.x from stable-2.10
16:26:02 <samccann> heh sorry. was typing up my what's next
16:26:10 <acozine> np
16:26:45 <acozine> okay, that sounds like "work we know we need to do" rather than discussion we need to have or decision we need to make
16:27:02 <acozine> I'm going to jump ahead on the agenda because it's getting late where gwmngilfen is . . .
16:27:05 <samccann> #action samccann work with abadger1999 to determine how this works with Ansible package 3.x build out of stable-2.10 and the ability to continue publishing Ansible 2.10 docs for some time to come.
16:27:10 <gwmngilfen> eh no it isnt
16:27:15 <gwmngilfen> 16.30 atm
16:27:21 <samccann> i think w'ere done w/ this topic for now anyway
16:27:32 <acozine> #topic more details on docs user survey results
16:27:33 <abadger1999> <nod>
16:27:53 <acozine> gwmngilfen: you're on
16:27:58 <gwmngilfen> heh
16:28:19 <gwmngilfen> so, ive spent a few days doing some modelling with the survey data to see what we can discover
16:28:44 <gwmngilfen> acozine and I are planning to get some blog posts out on the subject so you'll be able to read it all, but here's a few headlines
16:29:06 <gwmngilfen> (acozine correct me if I misremember things)
16:29:35 <gwmngilfen> so, firstly,  the context is that the survey is broadly positive - by far the docs users are more happy than not. keep that in mind
16:29:59 <acozine> hooray!
16:30:15 <gwmngilfen> that said, we asked questions about people's experience, time with ansible, role, and their goals from the docs (as well as side questions on github use and languages)
16:30:16 <samccann> \o/
16:30:31 <lmodemal> Yay!
16:30:55 <gwmngilfen> on time/experience, these turn out to be highly correlated (not surprising, you cant have experience of something you spent zero time with), so I picked just "time"
16:31:19 <gwmngilfen> there's some evidence that long-time users are less happy with the docs than newer users
16:31:51 <gwmngilfen> a user in the "4 or more years" category has about a 25% lower chance of giving you a Very Happy answer than a new user. I'll come back to why in a mo
16:32:02 <acozine> for context: the question on time was "how long have you been using Ansible"; the question on experience was "do you consider yourself a beginner, an expert, or in between"
16:33:07 <gwmngilfen> thanks
16:33:07 <gwmngilfen> for role, with "Other" as a reference, it seems we pretty much hit the mark for sysadmins, but less so for developers (-21% there). interestingly we forgot to add "DevOps" as an option - thats one for the post mortem
16:33:30 <gwmngilfen> the other categories are more variable as we have limited data, but it seem Network Admins really like the docs :)
16:34:32 <gwmngilfen> finally on goal, against referenced against "Other", all the specific goals do well. The lowest performer was "Looking for specific docs on module/plugin" at exactly 0%
16:34:42 <gwmngilfen> the rest are all positive
16:35:13 <gwmngilfen> so, tying that together, I think it makes sense - devs/longer-time users are more likely to be looking for something specific
16:35:30 <acozine> again, context - 0% means the people who said they were looking for specific docs on modules/plugins were no more and no less likely than the reference group to be happy with the docs, right?
16:35:46 <samccann> is there any indication that some of the problems could be 'findability'?  as in looking for specific module docs - is it because they couldn't find it, or what they found was lacking examples etc?
16:36:13 <gwmngilfen> thus is follows that those areas would come out lower than others.
16:36:15 <gwmngilfen> again, context is key - even in the lowest categories, these users are less happy but they are not unhappy
16:36:26 <gwmngilfen> acozine: correct, "Other" is the reference
16:36:26 <gwmngilfen> samccann yes, coming to that
16:36:41 <gwmngilfen> so we asked two open-text questions, which total got ~1200 replies
16:37:11 <gwmngilfen> thats hard to read through, so I did some text analysis, and yes, structure, findability, and similiar themes are what come through
16:37:24 <gwmngilfen> I'm trying to avoid posting many many pictures to chat, but heres one
16:37:37 * gwmngilfen uploaded an image: image.png (273KiB) < https://matrix.org/_matrix/media/r0/download/matrix.org/CpqedcdoIcgxrjprllFRlfVy/image.png >
16:37:41 <briantist> for me, I'd say findability _can_ be a problem, but the bigger issue is missing or outdated docs
16:38:12 <gwmngilfen> words that are higher up (Y-axis) are more frequent, words on the left had lower ratings for the docs overall
16:38:13 <acozine> I spot-checked the responses, a lot of people complained about the disappearance of the all-modules index page, which we have now restored (thanks felixfontein!)
16:38:34 <gwmngilfen> you can see that structure is a common theme on the left
16:38:53 <gwmngilfen> yes, acozine told me that - it's reassuring when the analysis matches expectations :P
16:39:26 <acozine> yeah, along with "find" and "search" - folks also said that site search is bad, they go to google instead
16:39:37 <lmodemal> I've heard that too
16:40:00 <acozine> briantist: that's good feedback - when you run into missing/outdated things, is it usually module/plugin docs? or more general topics?
16:40:01 <briantist> that's 100% true.. every once in a while I try to use the search and then go right back to google
16:40:11 <gwmngilfen> indeed, see navigation, links, etc n the middle of the plot
16:40:11 <gwmngilfen> as for github, just to wrap up, we did ask what stops people contributing and one theme there is not feeling like they have enough experience - this might be worth a marketing drive at some point
16:40:30 <gwmngilfen> since even a typo fix is generally welcome :)
16:40:42 <acozine> typo fixes are ALWAYS welcome
16:40:50 <gwmngilfen> ok, that wraps me up i think. my blog should be up this week, i'll post it here when it is
16:40:59 <acozine> thanks gwmngilfen
16:41:14 <samccann> cool thanks!
16:41:24 <lmodemal> Thanks gwmngilfen!
16:41:37 <gwmngilfen> my pleasure, its what i'm here for :)
16:42:05 <briantist> acozine: I was going to just throw this into open floor actually, but an example from yesterday: I'm starting to write unit tests in a collection I manage, having never written units in ansible or in python before. There are docs about it, but they focus on `unittest`, while also saying they drive tests through `pytest`. I got confused because I didn't even realize they were different. Looking at others' unit
16:42:05 <briantist> tests, both are used. When I asked in #ansible-devel which framework I should use, answer was definitively `pytest`,  but docs still primarily reference the other framework
16:42:27 <briantist> so tl;dr, I'd say it's for general topics
16:43:10 <acozine> briantist: thanks, if you have the time/interest in opening a PR to add what you learn, that would be awesome; meanwhile we'll add that to the queue
16:43:29 <briantist> especially developer stuff; the deprecation support in env vars in plugins for example, is not documented anywhere, use of `vars:` , etc. lots of stuff core engine supports and is in use, but not really described
16:43:53 <briantist> I would normally consider that,  but I'm extremely new to writing units in both python and ansible, so it's hard to write that
16:44:37 <samccann> briantist: even opening an issue and putting in that what you are learning along the way is a start.
16:44:48 <acozine> understood, no pressure on creating a PR, this is good feedback for us
16:45:36 <acozine> anything else on the Survey results and/or areas for improvement, generally speaking?
16:45:57 <acozine> okay, we've got fifteen minutes left
16:46:16 <acozine> I'm going to do a quick update on two of my action items, then open up the floor
16:46:20 <briantist> thanks, yeah I'd consider it, but I'm just getting my feet wet, also some people are good at incrementally taking notes and making stuff like that (I envy them), for me, I find it difficult to write anything without a near-full understanding 😅
16:46:41 <acozine> #topic backports status
16:46:58 <acozine> we've got 7 docs backports open, I should be able to merge them today
16:46:59 <acozine> https://github.com/ansible/ansible/pulls?q=is%3Apr+is%3Aopen+label%3Adocs+label%3Abackport
16:47:25 <acozine> if anyone has stuff they've been meaning to backport, today would be a great day to open that backport PR!
16:47:58 <felixfontein> yay for merging backports :)
16:48:09 <acozine> I'm still getting used to the new release cadence, which means backporting is frozen every three weeks during release time
16:48:18 <samccann> felixfontein: we didn't backport that sphinx 2.1.2 requirement to 2.10 because it impacted sanity tests and was deemed not a good idea
16:48:25 <dericcrago> from personal experience I would second what briantist said, documentation around usage was always awesome, but once you started getting into development it could be hard to find what you were looking for, the majority of the documenation for connection plugins for example is "see examples" :) https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html#connection-plugins
16:48:34 <acozine> felixfontein: should've been done sooner, but better late than never
16:48:36 <samccann> does that impact what you had going (and building Ansible 3.x?)
16:49:31 <felixfontein> samccann: yes, I heard, but with another antsibull release that isn't necessary anymore anyway :)
16:49:40 <samccann> oh phew!
16:49:55 <acozine> dericcrago: yes, we could be more helpful there, do you know anyone who could help us extend the Developing Plugins content?
16:50:05 <felixfontein> dericcrago: probably the core team needs more reminders to document new features they add. and community members adding new features to also document them :)
16:50:20 <acozine> it's not my area of expertise, but I'm happy to take outlines/drafts/notes and turn them into polished docs
16:50:51 <acozine> maybe we can put out a "call for docs" at the next contributor summit that focuses specifically on the developer guide
16:51:05 <samccann> yeah that ^^ is my general problem w/ developer docs. would love to get better at it, but for user docs, I can... USE ansible and find the problems in the docs... for developer stuff, I can't ..erm.. 'develop' and find problems in the docs.
16:51:07 <briantist> +1 felixfontein , at work I try to promote the idea that a feature/project/etc. is not done until the documentation is done, more feedback about that in PRs would be great to promote writing the docs while the information is fresh
16:51:43 <acozine> sadly, the docs team only gets pinged on PRs that already have docs included . . .
16:52:03 <samccann> is there a way we can get ansibot to 'nag' a 'feature' labeled pr to say 'did you add docs'? :-)
16:52:11 <acozine> so we don't get much of a chance to say, "Hey, please add docs", only "here's how I'd improve these docs you wrote"
16:52:12 <samccann> feature or enhancement etc.
16:52:18 <briantist> yeah.. that sounds like a culture / cross-team collaboration issue :-/ always tough
16:52:38 <acozine> samccann: that's an interesting idea
16:53:26 <acozine> right now I don't think it even nags about changelog entries
16:53:35 <dericcrago> acozine - unfortunately, no. I stumbled through it several years ago and haven't really looked at it since. :(
16:53:58 <acozine> but that might be a place to start for newer features - go through the changelog and compare it to the docs to see if we cover the topic
16:54:58 <acozine> this could definitely be a reason why developers are less happy than other docs users
16:55:22 <lmodemal> I agree acozine
16:55:24 <acozine> something to add to the 2021 Docs Plan
16:55:33 <acozine> meanwhile, we've got five minutes left
16:55:42 <felixfontein> yep. also reminding the core team from time to time might increase awareness :)
16:55:53 <samccann> i think if we can identify the top 10 'tasks' that developers do, we can target those pages for improvement
16:57:22 <acozine> #info developer guide could use more detail, more updates - explore ways to encourage adding docs with new features and/or expanding existing developer docs
16:57:41 <acozine> #topic /docs/ folder in collections update
16:57:45 <acozine> this one is really quick
16:58:37 <acozine> I need to connect with the Galaxy team and other folks internally to get their thoughts on the future of the /docs/ folder in collections
16:59:03 <sommersoft> had a phone call and had to step away. i'm working on https://github.com/ansible/ansibullbot/issues/1047, and have a working skeleton atm. it could possibly be extended to help enforce docs for [new] features, or at least tagging/notifying.
16:59:14 <acozine> sommersoft: thanks!
16:59:21 <lmodemal> Thanks sommersoft!
16:59:36 <acozine> okay, we'll run five minutes over for a quick
16:59:40 <acozine> #topic open floor
16:59:59 <acozine> all questions, ideas, comments, concerns, critiques, suggestions welcome
17:00:37 <briantist> I'm certainly interested in whatever `/docs/` will be. I've been thinking about how/where to write "associated" documentation for my collection, whether it would/should get published to docsite, whether I should use the repo's wiki, etc.
17:00:44 <acozine> if you have a PR that's not getting any reviews, or an issue that needs more attention, please post them!
17:01:17 <acozine> briantist: do you have strong preferences for where your collection docs get published, or for what format you use?
17:01:45 <acozine> i.e. do you want to see them on docs.ansible.com? would you prefer to host them on your own website?
17:01:47 <briantist> not at the moment no, although I'd probably prefer not to write in straight RST
17:01:58 <briantist> I don't want to maintain a separate website for them
17:02:27 <samccann> what would you write in if not rst? just curious
17:02:47 <briantist> markdown; I just know the syntax better, RST means I have to keep stoppng to look at a reference
17:02:58 <briantist> if they get published to docs that'd be fine, I might also be fine with just using the github wiki, etc. I don't have any docs now anyway
17:03:00 <samccann> a gotcha
17:03:02 <acozine> if you could copy an RST template and just fill in the text, would that work?
17:03:17 <briantist> just mentioning I'm interested in the future of docs, whatever that is :)
17:03:25 <acozine> that is awesome
17:03:39 <acozine> we'll be discussing the possibilities over the next few weeks/months
17:03:48 <acozine> hope to have a path forward by summer
17:04:08 <acozine> so . . . stay tuned!
17:04:48 <briantist> cool 👍
17:04:56 <acozine> any other topics for the open floor?
17:05:31 <acozine> everyone is welcome to bring up any topic during the open floor
17:05:43 <acozine> you don't have to be a "chair" or anything
17:06:23 <acozine> open floor going once . . .
17:06:42 <acozine> going twice . . .
17:07:09 <acozine> as a reminder, the official meeting agenda lives at https://github.com/ansible/community/issues/579
17:07:15 <acozine> all are welcome to add topics
17:07:20 <acozine> just add a comment to the bottom
17:07:40 <acozine> thanks abadger1999 briantist dericcrago felixfontein gwmngilfen lmodemal samccann sommersoft
17:07:42 <lmodemal> Thanks everyone!
17:07:47 <gwmngilfen> acozine++
17:08:00 <acozine> see you next week
17:08:02 <acozine> #endmeeting