16:01:35 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:01:35 <zodbot> Meeting started Tue Mar  7 16:01:35 2023 UTC.
16:01:35 <zodbot> This meeting is logged and archived in a public location.
16:01:35 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:01:35 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:35 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:01:36 <samccann> .ping
16:01:36 <zodbot> pong
16:01:41 <samccann> phew
16:01:44 <samccann> @room Meeting time! Who is here to talk the docs?
16:01:56 <acozine> o/
16:02:06 <samccann> #chair acozine
16:02:06 <zodbot> Current chairs: acozine samccann
16:02:14 <samccann> Raise your ascii hand (o/) to say hi or any other way you want to let us know you are here. And Welcome to any new folks!
16:02:21 <samccann> To any newcomers - again, welcome. We chair all attendees as a way of recognizing your time spent here. And it opens it up for people to add to the meeting minutes with commands like #info or #link (to add a link)
16:02:23 <acozine> hooray for the return of zodbot!
16:02:27 <tremble> o/ (at least for a little while)
16:02:27 <oranod> o/
16:02:29 <samccann> General run of the meeting - We go over action items, give docs updates.. maybe have a topic or two, and go over doctooling updates (all the fun stuff behind the scenes that get us docs.ansible.com!)
16:02:30 <oranod> hi all
16:02:41 <samccann> #chair tremble Don Naro
16:02:41 <zodbot> Current chairs: Don Naro acozine samccann tremble
16:02:44 <samccann> welcome welcome
16:03:02 <samccann> felixfontein: briantist - around to talk docs today?
16:03:27 * gwmngilfen-work > <@acozine:ansible.im> hooray for the return of zodbot!
16:03:27 * gwmngilfen-work is totally going to write a new matrix zodbot ... ;)
16:03:30 <briantist> o/  (truthfully I'll be very distracted, in another important meeting)
16:03:45 <acozine> heh, any day now?
16:03:47 * samccann is ready to test it in DaWGs land as soon as you do
16:04:11 <gwmngilfen-work> after i write that IRC-Matrix bridge naming bot I've talked about for checks watch 12 months
16:04:11 <kristianheljas> \o (mostly listatening along again)
16:04:13 <samccann> #chair briantist kristianheljas Gwmngilfen
16:04:13 <zodbot> Current chairs: Don Gwmngilfen Naro acozine briantist kristianheljas samccann tremble
16:04:18 <acozine> briantist: with the bot helping, we can take good notes for you!
16:04:27 <samccann> hehe yep. and thanks!
16:04:46 <samccann> official agenda at https://github.com/ansible/community/issues/678#issuecomment-1448521392
16:05:13 <samccann> #topic Action Item updates:
16:05:17 <samccann> hmm... I don't have any open items listed.. is it possible we're all caught up?!?!
16:05:38 <acozine> whaaaat?
16:05:42 <acozine> that would be amazing!
16:06:02 <samccann> heh or... I'm forgetting to create action items lol
16:06:03 <samccann> meanwhile.. we roll on!
16:06:10 <samccann> #topic docs landing pages
16:06:28 <samccann> Don Naro: since you've got the exciting stuff, you want to lead us off today?
16:06:40 <oranod> sure. is this exciting? lol
16:07:30 <oranod> #info the community team has put together a first set of user journeys based on the personas, which are available at https://github.com/ansible/docsite/blob/personas/user-journeys/ansible-user-journey-maps.md
16:07:54 <oranod> #info we'd love to get review and feedback / whatever input folks in the community have got
16:08:46 <oranod> #info we're using these journeys to build a new docsite that will replace docs.ansible.com in a few weeks. you can find the work in progress site (and send a PR to help) here: https://github.com/ansible/jinja-docsite
16:09:03 <oranod> feel free to pick off something from the list of open issues: https://github.com/ansible/jinja-docsite/issues
16:09:47 <oranod> I'm currently working on filling out all the pages with content from the journeys
16:09:49 <samccann> #info you can see the WIP docsite at  -https://ansible.github.io/jinja-docsite/
16:10:21 <samccann> so as Don said, this is designed based on those user journeys in https://github.com/ansible/docsite/blob/personas/user-journeys/ansible-user-journey-maps.md
16:11:23 <acozine> At a first glance, the user journeys look a lot like tutorials, is that the intention?
16:11:34 <acozine> s/user journeys/ docs built on user journeys
16:11:46 <samccann> The intention is to help the reader advance their Ansible skills, so yeah can feel like that
16:12:26 <samccann> Ideally, we have a docsite that helps people progress from  'what is this Ansible thing' to 'Hey wow I'm on the steering committee now.. woot!"
16:12:26 <samccann> and all stops in between :-)
16:13:12 <oranod> the basic idea is that each persona has a set of milestones, and each milestone has specific actions that they need to complete to achieve that milestone
16:13:35 <tremble> That's very blue :)  Looks good
16:13:39 <acozine> That is awesome. I'd like to make sure that we preserve easy ways for educated users to find specific topics - for example, the variable precedence list.
16:13:49 <kristianheljas> And jinja!
16:14:00 <bcoca> cd work/ansible && git grep precedence
16:14:05 * bcoca ducks
16:14:07 <kristianheljas> ^ folks are so confused about jinja
16:14:33 <bcoca> i've been using jinja 18 yrs, still confused sometimes
16:14:50 <bcoca> i've also read/modify the jinja source code, still confused
16:15:16 <samccann> #info docsite should help experienced users find things quickly like precidence list, jinja2 help etc
16:15:40 <samccann> Don Naro: do you want feedback like this as issues opened in the repo?
16:15:56 <oranod> samccann: that would be great. yes, please.
16:16:07 <samccann> or do you want to open a community-topic to gather a bunch more feedback?
16:16:16 <oranod> I was thinking I could open issues but if someone else wants to do that, I'm cool with it too
16:16:48 <oranod> well we could use the existing community topic, which is maybe somewhat neglected...
16:17:10 <oranod> #info folks can add feedback to https://github.com/ansible-community/community-topics/issues/175
16:17:14 <samccann> Maybe put a link to the demo page where people can see it 'live' so to speak
16:17:24 <samccann> And then another call in bullhorn/reddit/etc?
16:17:47 <oranod> you mean put the link in the community-topic?
16:17:47 <samccann> OR did you want to wait until you have the other two/three pages drafted ?
16:18:32 <oranod> honestly it might be good to have the rest of the content based on journeys up first, so people aren't looking at placeholder lorem ipsum
16:20:07 <samccann> ok yeah. Is that this week? Do you need help etc?
16:20:25 <samccann> seems like the journeys are defined, so someone else, if interested, could pick an issue and fill out that page?
16:21:04 <oranod> totally, as mentioned earlier, feel free to grab one of the issues here and start hacking: https://github.com/ansible/jinja-docsite/issues
16:21:25 <oranod> if anyone out there is interested in helping make this site more mobile friendly / responsive, that'd be great
16:21:47 <samccann> #info we need some help fleshing out the WIP pages - feel free to grab one of the issues here and start hacking: https://github.com/ansible/jinja-docsite/issues
16:22:03 <samccann> #info these are based on the journeys defined in https://github.com/ansible/docsite/blob/personas/user-journeys/ansible-user-journey-maps.md
16:22:40 <samccann> good stuff!
16:23:05 <samccann> so folks, open issues with feedback ideas or  things you think need to change or be enhanced etc.
16:23:43 <samccann> #action all - open issues on https://github.com/ansible/jinja-docsite/issues for your feedback on the current design at https://ansible.github.io/jinja-docsite/
16:24:04 <samccann> oh look, an action item!
16:24:14 <samccann> okay anything else around the new docsite prototype and general direction?
16:24:41 <oranod> not from me, thanks
16:24:52 <samccann> what I've heard so far - it's very blue :-) and we need more quick-links for the intermediate folks (jinja2 and variable precidence)
16:25:23 <acozine> quicklinks or maybe a site index for core docs?
16:26:19 <acozine> something that serves the reader who's thinking "I know how to use Ansible, I just need the docs on strategies" or whatever
16:26:20 <oranod> yeah we talked about a sitemap as part of the footer
16:26:23 <oranod> it's a good idea
16:27:17 <samccann> ok I added that comment to the footer issue
16:28:32 <acozine> thanks samccann
16:28:43 <samccann> and I opened https://github.com/ansible/jinja-docsite/issues/35
16:28:58 <samccann> for the quick links. We can't put a ton up, but we could add a couple.
16:29:26 <samccann> I wanna say based on docsite hits, yaml syntax is one of THE most visited pages.
16:29:41 <samccann> #action samccann to review top page hits and add to https://github.com/ansible/jinja-docsite/issues/35 as potential quicklinks
16:29:48 <samccann> ok thanks everyone!
16:30:01 <oranod> indeed, thank you!
16:30:35 <oranod> hopefully this effort leads to some good improvements that help sustain and grow the community
16:31:39 <kristianheljas> segmenting the docs certanly will help, there is so much of it and grouping it by experience level seems like a really good idea!
16:32:04 <samccann> yeah so far, the docs will still look the same as docs.ansible.com/ansible
16:32:25 <samccann> these are just the pages in front of all that, so readers can hope right  to important sections based on their current skills/needs
16:32:45 <samccann> so will replace the pages with the big boxes you see today on docs.ansible.com
16:33:07 <bcoca> introduction/tutorial, intermediate, advanced, peoplewithnolife
16:33:33 <bcoca> https://www.lilatomic.ca/posts/ansible_httpapi_plugins/ <= has some VERY good plugin dev articles
16:34:31 <kristianheljas> samccann: that's what i meant about segmenting, right now these docs are all across the docsite
16:34:33 <samccann> actually bcoca brings up an interesting 'meta' issue - today we don't really link out to other people's 'stuff' that might actually be very usefil
16:35:01 <samccann> #topic linking to external useful content for learners
16:35:26 <samccann> #info where could we use/highlight good external content like https://www.lilatomic.ca/posts/ansible_httpapi_plugins/
16:35:43 <bcoca> well, there are sevearl divisions to be made also by role/audience   user/pb/role author/ plugin developer/ engine/tools dev
16:35:46 <samccann> So we do have See Also sections on some docs, but again, most if not all are linking to our own stuff
16:36:33 <samccann> I'm wondering - do we open that up to put some links in to stuff like this (based on community recommendations)
16:36:42 <samccann> do we save it for 'some other place'?
16:37:19 <samccann> like a 'handy videos and learning' section potentially outside of docs?
16:38:53 <samccann> ...ok not hearing much for that idea
16:38:55 <samccann> :-)
16:39:05 <acozine> hm, linking to external sites could get tricky
16:39:09 <kristianheljas> thats'a good question. I have another: how do we deal with dead links
16:39:27 <acozine> do we do it for anyone who asks? do we have a review process?
16:39:27 <samccann> it's possible there will be a way to highlight that based on the strategy stuff Gwmngilfen set out earlier
16:39:34 <samccann> yeah two very good points
16:39:55 <acozine> would we ever get rid of any links? how/when?
16:40:12 <samccann> on broken links - I tried a link checker and it pulled out too much false positives so to speak.  But we do need something like that for sure so open to suggestions
16:40:13 * gwmngilfen-work catches up
16:40:14 <kristianheljas> they also get outdated
16:40:35 <tremble> Would it be worth just having a daily link crawler looking for broken links off the main sites?
16:40:35 <samccann> acozine: excellent points on how we control (or not control?) the quality of shared external resources
16:40:40 <gwmngilfen-work> kristianheljas: everything gets outdated 🙂
16:40:42 <acozine> it's not just broken links, but things like outdated blog posts
16:41:04 <acozine> heh
16:41:05 <kristianheljas> seems like bullhorn (or other community platforms) is for such things
16:41:05 <gwmngilfen-work> it's a fair point, and one that needs more thought
16:41:12 <samccann> kristianheljas: very true
16:41:17 <kristianheljas> at least for now
16:41:47 <tremble> bullhorn's great for "here's a cool new thing" people won't use it when they're looking to solve a problem "today"
16:41:47 <samccann> what I wonder is - do 'some resources' get to a point that folks are using them frequently and we should just add links?
16:42:11 <samccann> we don't typically do that in 'traditional' techdocs but figured I'd ask
16:42:12 <kristianheljas> tremble: good point
16:42:24 <acozine> yeah, it could be really useful - there are a lot of posts out there that cover material we don't really have in the docs today
16:42:43 <gwmngilfen-work> the idea of an Ansible Planet has been raised before too, these are all related topics - it's not just about docs
16:42:52 <tremble> There are so many really good resources out there, but I'm sure we'd need a "here lie dragons" warning about any external docs.
16:42:52 <acozine> I just think we'd need a maintenance strategy going in
16:43:20 <acozine> tremble: indeed
16:43:20 <gwmngilfen-work> one thing is for sure, it doesn't need to be decided immediately. lets all give it some thought
16:43:27 <kristianheljas> Gwmngilfen's forum idea might fit this well
16:43:59 <kristianheljas> ie a subforum for user generated docs/tutorials
16:43:59 <samccann> yeah good ideas
16:44:40 <tremble> There are two things we'd want to check for: 1) is it still what it used to be  2) has a breaking change / deprecation made the doc outdates
16:44:40 <acozine> the closest thing we have in the docs now is the "tools" page
16:44:41 <samccann> tremble: yeah that's the quality checks acozing was mentioning
16:44:49 <acozine> maybe that could be a model somehow?
16:44:51 <samccann> acoZING!
16:44:55 <acozine> heh
16:46:24 <tremble> I like what the UK health service does on all their pages they explicitly state when any content was "last reviewed".  That might be good for any external links.  "We last did a sanity check on".
16:46:24 <samccann> we'd need volunteers to do those quality checks now and then of course
16:46:27 <gwmngilfen-work> ooh, yes, thats nice. its also a nice easy task to get new people involved
16:46:50 <gwmngilfen-work> giving people tasks appropriate to their experience is critical in building participation 🙂
16:47:46 <kristianheljas> there are certianly SEO/security aspects about external links on *.ansible.com as well
16:47:54 <kristianheljas> stuff may change after Qa
16:48:42 <tremble> Yeah, this all feels like an ansible.community vs ansible.com thing
16:48:42 <kristianheljas> even then, we need to keep the trust 🙂
16:49:25 <samccann> good points tremble
16:49:40 <samccann> #topic Open Floor
16:50:04 <samccann> since we have a few minutes left, anything docs related anyone wants to bring up?
16:51:17 <samccann> ok seems all quiet.. shall we end early today?
16:51:50 <oranod> I don't want to hog the floor but it'd be good to remind about the votes for semantic markup and private plugins for Felix
16:52:00 <samccann> sure go for it!
16:53:52 <tremble> kristianheljas: As soon as we link to something external there's only so much we can do.  "Here be dragons", "How to report dodgy content" and "last reviewed", are probably about as far as anyone could go.
16:53:52 <oranod> #info everyone who hasn't yet, please don't forget to participate in the vote for semantic markup (https://github.com/ansible-community/community-topics/discussions/205) and/or the vote for what kind of mechanism to use for private plugins in collections (https://github.com/ansible-community/community-topics/discussions/204)
16:54:55 <oranod> > once semantic markup support is 'approved', I'd merge the antsibull-docs PR and create a new release soon, and then a follow-up PR for ansible/ansible to bump the antsibull-docs dependency; the ansible-core PRs (semantic markup support for ansible-doc, and bumping the antsibull-docs dependency) can hopefully get merged before feature freeze as well
16:54:55 <oranod> # info it would be good to discuss how we can help get the word out and help move this forward
16:55:18 <oranod> s/# info//
16:56:04 <oranod> that turned out a little weird format-wise but it's a quote from Felix earlier today before the DaWGs. I'm sure he'll have everything covered but I'd be interested in helping him get that going.
16:56:12 <samccann> yeah we'd need that stuff merged soonish so we could test it all out (and get any bugs fixed) before the 2.15 branch pull if that's the target
16:56:16 <samccann> or else it waits til 2.16
16:57:17 <samccann> meanwhile on the vote early vote often:
16:57:31 <samccann> #info voting started for the community planning strategy - https://github.com/ansible-community/community-topics/issues/201#issuecomment-1458480432
16:57:53 <samccann> Link to the vote there. please read and vote as it's setting the overall strategy for the ansible community (beyond just docs)
16:58:19 <samccann> ok I need to hop for another meeting
16:58:19 <samccann> thanks everyone!
16:58:20 <samccann> #endmeeting