16:01:51 <samccann1> #startmeeting Documentation Working Group aka DaWGs
16:01:51 <zodbot> Meeting started Tue Nov 15 16:01:51 2022 UTC.
16:01:51 <zodbot> This meeting is logged and archived in a public location.
16:01:51 <zodbot> The chair is samccann1. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:01:51 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:01:51 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:02:03 <samccann1> @room Meeting time! Who is here to talk the docs?
16:02:10 <thedoubl3j> o/
16:02:11 <samccann1> 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:24 <samccann1> #chair thedoubl3j
16:02:24 <zodbot> Current chairs: samccann1 thedoubl3j
16:02:26 <samccann1> welcome! long time no see!
16:02:34 <DonNaro[m]> o/
16:02:40 <samccann1> 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:42 <DonNaro[m]> hello
16:02:48 <samccann1> #chair Don Naro
16:02:48 <zodbot> Current chairs: Don Naro samccann1 thedoubl3j
16:03:00 <samccann1> 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:03:09 <thedoubl3j> howdy
16:04:01 <felixfontein> o/
16:04:03 <felixfontein> (partially there)
16:04:10 <samccann1> #chair felixfontein
16:04:10 <zodbot> Current chairs: Don Naro felixfontein samccann1 thedoubl3j
16:04:23 <samccann1> briantist: - around to talk docs today?
16:04:23 <acozine> o/
16:04:31 <samccann1> #chair acozine
16:04:31 <zodbot> Current chairs: Don Naro acozine felixfontein samccann1 thedoubl3j
16:04:54 <DonNaro[m]> hey felixfontein and acozine
16:05:08 <acozine> hey Don Naro
16:05:14 <samccann1> Official agenda is https://github.com/ansible/community/issues/643#issuecomment-1307505913
16:05:42 <samccann1> #topic Action Item updates:
16:05:52 <samccann1> #info Resolved - add an intro to the agenda for welcome/here's what you need to know/ etc so newcomers can prepare.
16:06:03 <briantist> o/
16:06:09 <samccann1> #info resolved  - to discuss antsibull-doc bugfix releases and can we update in stable-2.14 w/o updating CI containers.
16:06:14 <samccann1> #chair briantist
16:06:14 <zodbot> Current chairs: Don Naro acozine briantist felixfontein samccann1 thedoubl3j
16:06:18 <samccann1> welcome welcome everyone!
16:06:37 <DonNaro[m]> hello briantist
16:06:42 <samccann1> #info open - samccann shift meeting  time in calendar and remindbot to 1 hr later
16:07:09 <samccann1> I managed half of that but messed up remindbot. So.. at some random point this week, remindbot will go off if I don't delete it and try again
16:07:16 <anwesha[m]> Hello everyone
16:07:24 <samccann1> #chair anwesha
16:07:24 <zodbot> Current chairs: Don Naro acozine anwesha briantist felixfontein samccann1 thedoubl3j
16:07:50 <samccann1> Welcome welcome!  anwesha is our newest addition to the RH community engineering team!
16:08:02 <DonNaro[m]> hey anwesha !!
16:08:07 <thedoubl3j> welcome!
16:08:15 * bcoca waves
16:08:18 <briantist> welcome anwesha[m] !
16:08:31 <samccann1> #chair bcoca
16:08:31 <zodbot> Current chairs: Don Naro acozine anwesha bcoca briantist felixfontein samccann1 thedoubl3j
16:08:44 <samccann1> because all waves get tossed into a comfy chair round here!
16:09:12 <samccann1> Don Naro: any progress on the EMEA open office hrs or open docs chat  time etc?
16:09:40 <anwesha[m]> Thank you thedoubl3j briantist
16:10:37 <DonNaro[m]> samccann: no there isn't much of an update there. no more responses to the survey anywhoo.
16:12:37 * samccann1 can't tell if don is writing a novel in response or of matrix just tricking me
16:13:09 <DonNaro[m]> ah, I'm the kind of stop/start messaging. I'm just faffing about on my keyboard honestly.
16:13:14 <samccann1> hah ok
16:13:16 <DonNaro[m]> never trust that "is typing" thing
16:13:20 <samccann1> gonna move on then lol
16:13:35 <samccann1> yeah I'm never sure. I don't want to interrupt someone, but seems like it's a false flag
16:13:42 <samccann1> #topic Documentation updates
16:13:49 <samccann1> #info Ansible 7 rc1 is out today. staging at http://docs.testing.ansible.com/ansible/7/index.html
16:14:03 <samccann1> well staging is in progress. should be live in the next 15 min or so.
16:14:55 <samccann1> #info archiving 2.4 next.
16:15:23 <samccann1> I'm staging it now. Once it's in production, I'll announce in the bullhorn so peeps can change bookmarks before we turn on the redirects.
16:16:01 <samccann1> #topic What's Next
16:16:04 <samccann1> #info Looking for thoughts on where we should target docs improvements next?
16:16:04 <samccann1> https://github.com/ansible-community/community-topics/issues/81 to add your ideas.
16:16:56 <bcoca> separate site docs from per version docs?
16:17:08 <samccann1> One thing we'll be Thinking Deep Thoughts(tm) about in the coming months - defining 'personas' for Ansible community folks. This is a fancy marketing term that basically means - how do we sort folks
16:17:38 <bcoca> samccann1: he, we did that a few years back : user/content author/plugin dev/core dev
16:17:42 <samccann1> based on what they want from the docs - users vs contributors vs contributors who code (aka developers) vs..well who knows
16:18:20 <samccann1> bcoca: separate site docs from per version docs -the perrenial ask. Alas we need a better search solution to do that, but yeah not off the list , just ...TBD
16:18:21 <bcoca> content = playbook/role writer
16:18:34 <samccann1> bcoca: do you have anything that goes more in depth on those?
16:18:45 <bcoca> samccann1: search > separation ... search has alwasy been a problem since day1
16:18:55 <samccann1> heh. Truth
16:19:26 <bcoca> user => runs play/playbooks, content author-> writes and distributes playbooks/roles, plugin dev-> writes/distirbutes plugins (mostly  modules) .. core dev => me
16:19:47 <samccann1> so we have content users, content creators (playbooks ,roles etc) and content developers (develop plugins, collections etc).
16:19:48 <bcoca> and people that want to contribute to core itself (minority at this point sinc emost were plugin devs adding plugins to core)
16:20:22 <samccann1> But we also have 'contributors' who can run the gambit from driveby spelling PRs to meetup hosts, and significant overlap with those content developers.
16:20:24 <bcoca> yep, its fine if we drop 4th since its very small and VERY techinical audience at thsi point
16:20:48 <bcoca> samccann1: every person can have diff personas at diff times (i'm all 4!)
16:21:19 <bcoca> 1 and 2 have much overlap, 3 a bit less
16:21:57 <bcoca> really awx/AAP users are ones that can fit 'squarely in 1' but not be 2
16:22:02 <samccann1> bcoca: yeah I wondered about that as well. How many of our community folks are just USING someone else's playbooks/roles?  Seems most would actually be creating or modifying playbooks etc
16:22:40 <samccann1> Well from the broadeest perspective, we'd want to include AWX users as part of the Ansible community. We don't do a great job of that right now so that's a longer term goal
16:22:46 <bcoca> while ansible-navigator users are 2&1 mostly in service of 'pure 1' that will be awx/AAP user
16:23:10 <samccann1> thanks this helps
16:23:18 <bcoca> samccann1: i include everyone in Community, though i know others define it differently (free vs paid)
16:23:31 <samccann1> I'll write something up so we can all review etc at some point but these will be the main 3 to start
16:23:56 <DonNaro[m]> that's awesome
16:25:42 <samccann1> So on the version vs unversioned docs - do others have opinions on its relative priority?
16:25:43 <acozine> Personas were the basis for the current division of the Guides in the documentation - User Guide, Developer Guide, Contributor Guide. What is the next step in that evolution?
16:26:09 <samccann1> The idea for example that dev guides aren't really 'versioned' and neither are contributor guides.
16:26:10 <acozine> As in, what is the goal of extending those personas? Separate docsites?
16:26:40 <samccann1> acozine: the goal is less separate docsites but separate entries. Think of a much much better landing page at docs.ansible.com
16:26:52 <acozine> ah, yeah, that would be nice
16:27:17 <acozine> I tend to  skip those pages because I know the URL I need
16:27:26 <acozine> so I forget they exist
16:27:27 <samccann1> Also, as bcoca pointed out - the number of core contributors/coders is shrinking, but collection developers are growing. What does this mean for the existing dev guide etc
16:28:07 <samccann1> This was a page/site people liked - https://www.rdoproject.org/
16:28:31 <samccann1> so initially, we'd be talking better 'front pages' that lead people to the specific guide/sections that apply.
16:29:06 <bcoca> samccann1: dev and contributor will have versioning issues as API/features change
16:29:09 <bcoca> but less than user
16:29:23 <bcoca> what does not need versions are things like 'current policy' or 'current dev guidelines'
16:29:27 <briantist> I think a lot of non-core devs (like me) would be very interested in core docs
16:29:31 <bcoca> or release schedule ...
16:29:36 <samccann1> #info personas fit into 3 broad categories - content user (mostly awx) content creators (playbooks, roles, etc) and content developers ( writing plugins, contributing code etc)
16:30:46 <samccann1> @bcoca - let's see if I understand this correctly. If I'm writing a collection, I need different developer details if I'm targeting my collection at 2.14 vs say 2.12?
16:31:28 <samccann1> briantist: can you elaborate? even though you don't code in ansible/ansible itself, you see a need to review say a core developer guide?
16:31:39 <bcoca> samccann1: you might, there are features for collectiosn in 2.14 that dont exist in 2.12 .. i.e sidecar docs
16:31:42 <samccann1> or is it because currently, there's just one BIG OL developer guide that covers everything?
16:31:54 <briantist> review? no, but the content is very relevant to me as a developer
16:31:54 <samccann1> bcoca: thanks that helps
16:32:19 <briantist> I guess it would depend on what would go there vs. dev docs
16:32:37 <bcoca> if you create collection for >=2.14 you can put docs in .yml files, while collections for older versions .. those docs won't be seen
16:32:42 <samccann1> briantist: let's pretend for a moment, that I created a collection developer guide  that had everything in it that you needed. Would you still need core-specific dev guide?
16:33:00 <bcoca> in this case teh feature is 'backwards compatible' as older versions will ignore, but that is not true of all features
16:33:13 <briantist> well.. you've literally defined it such that I would not need it, because I everything I need is in the collection developer guide :p
16:34:55 <samccann1> heh yeah, I cheat.
16:35:06 <briantist> I can't the number of times I've had to step through core code to figure out how something works because it's not documented, either because it's related to what I'm developing or just out of curiosity
16:35:22 <samccann1> The thing is, with 'reused' content, we could do that - have a small core dev guide, and then 'reuse' what's appropriate in a much bigger collection dev guide.
16:35:23 <briantist> understanding the whole system is useful even if it's not necessary
16:36:07 <briantist> anyway, it would all depend on where the split is and what's actually there
16:36:11 <samccann1> ah.  So that's interesting briantist  - the notion that even a collection-only developer needs to understand how core is developed
16:36:14 <briantist> I suspect the lines are very blurry in places
16:36:21 <bcoca> briantist: true .. but sometimes 'understanding' involves putting yourself in a insane frame of mind ... see VariableManager ...
16:36:38 <briantist> bcoca: counting on it ;)
16:37:24 <samccann1> felixfontein: when you get a moment - what do you think about this notion of a separate collection developer guide (in full) vs a core-only developer guide?  Sounds like it may not be necessary/wanted vs keeping what we have today
16:37:41 * samccann1 sometimes suggests enhancements nobody wants or needs :-)
16:38:25 <felixfontein> samccann1: I think that separation would be a good idea
16:38:39 <bcoca> samccann1: like all humans do
16:38:53 <felixfontein> one question is what should happen with things that apply to both, like AnsibleModule documentation
16:39:10 <samccann1> it would effectively appear twice - once in each guide
16:39:20 <briantist> I think it sow up in both places
16:39:27 <briantist> should show up*
16:39:32 <samccann1> we can 'reuse' the source rst files so it would be the exact same info
16:39:52 <felixfontein> as long as it's the same source file... :)
16:39:54 <samccann1> it's just a case of - is it worth it? Does it help you as collection creators out
16:39:55 <bcoca> can use snippets to avoid duplicate sources, but still show 'duplicate end resulting docs'
16:39:57 <felixfontein> SEO folks will hate you for that though ;)
16:40:03 <bcoca> felixfontein: jinx
16:40:07 <samccann1> HAH
16:40:08 <briantist> one thing I would hope is that separating it encourages more docs from core on the various interfaces
16:40:22 <bcoca> briantist: one can hope ....
16:40:35 <samccann1> briantist: can you open an issue or three on what you feel is missing in dev docs?
16:41:02 <bcoca> 20-30 issues ...
16:41:09 <briantist> I cannot, there are too many things (sorry bcoca)
16:41:33 <samccann1> it's also possible I'm chasing rainbows here. I'm going under the assumption that the existing deve guide (other than the collection developer stuff) is still highly-focused on core development, which most of our readers aren't doing anymore
16:41:34 <bcoca> briantist: i agree, i've been making an effort to do so .. but always not enough time
16:41:56 <bcoca> samccann1: actually its more focused on plugin dev
16:42:05 <briantist> a lot of it is probably obscure, but there are things that I only know because of offhand comments (usually from bcoca but from others too)
16:42:07 <acozine> is this a case of "I don't know what I don't know" or are there specific documentation black holes that you keep running into?
16:42:57 <briantist> quick example: at some point I saw the comment "lookups are responsible for templating their own vars" or something like that.. this isn't in the docs anywhere as far as I know
16:43:01 <bcoca> acozine:  im guessing that the more they explore the known unkowns, new unkowns will sprout like weeds on the side of the road
16:43:05 <briantist> nor is how to do that
16:43:12 <samccann1> bcoca: so that suggests I am chasing rainbows if most of the dev guide is plugin development... because that's what collection creators do as well, right?
16:43:18 <bcoca> briantist: that is 1/2 true
16:43:28 <briantist> (am not asking for info on that right now, it's just an example)
16:43:39 <briantist> bcoca: yeah I don't even know how much of it is true and in what situations
16:43:47 <bcoca> they are responsible for templating their 'terms', the options have been 'fuzzy' and im trying to fix and define
16:43:54 <samccann1> briantist: that one seems very specific and worth a docs issue?
16:44:03 <acozine> briantist: that's helpful
16:44:17 <bcoca> samccann1: plugin development is not restricted to collecitons, collectiosn do not only contain plugins (playbooks/roles)
16:44:25 <briantist> right, and options vars are the ones I'm currently struggling with since I make heavy use of them but their use is limited sicne they are not templated
16:44:29 <acozine> also, I know what you mean about stray comments not making it into the docs
16:44:48 <bcoca> samccann1: kind of orthogonal , most 'public' collection devs are plugin devs, but most 'private' collection devs are for plays/roles for internal usage
16:45:04 <bcoca> collections are a way of packaging (but does influence dev)
16:45:24 <samccann1> thanks bcoca that helps
16:45:32 <bcoca> https://github.com/ansible/ansible/pull/79244 < briantist fixing that
16:46:24 <bcoca> so current plugin docs are 'generic' enough to work for both with minor edits (mostly import paths) for the differences between collection/non collection plugin
16:46:32 <briantist> folks like bcoca have tons of historical knowledge too that should be somewhere; understanding design decisions (even if it was organic, full of tradeoffs, etc.), understanding intent, is very helpful, I would love to see it documented
16:46:34 <bcoca> for plays/roles .. can be same, the differences are minor
16:47:12 <bcoca> briantist: most of it is 'documented' ... just very disperse ... irc meeting logs, proposals, tickets ... code comments ....sometimes even on the docsite!
16:47:46 <bcoca> though the last one is mostly when we are tired of responding to same question in ticket/irc/mailing list ....
16:47:47 <briantist> thanks for that PR, I was sad to see https://github.com/ansible/ansible/pull/58288 closed, didn't  know about the new one
16:47:49 <samccann1> briantist: that's tricky to do (including design decisions and tradeoffs) within a developer guide. That's more like specs that should be written and archived somewhere. I think OpenStack does that right? They have a design proposal phase etc
16:48:33 <bcoca> samccann1: very diff workflow than us .. we are mostly (design 3 things and accept another 50 adhoc)
16:48:47 <samccann1> heh yep
16:48:52 <bcoca> totally misused parens there ...
16:49:06 <samccann1> (that's okay)
16:49:07 <briantist> samccann1: I know it's tricky from a formatting perspective. I feel like the more technical type of stuff can be on top, it can link to a more long-form thing, or have it at the bottom or something. I definitely don't know the best way to present the info, I just know I want it 😁
16:49:09 <samccann1> ;-)
16:49:49 <samccann1> briantist: imo - the ideal point would be in the roadmaps. Right now there is usually a bullet list (of the 3 items bcoca mentioned)
16:50:27 <samccann1> Ideally each could link off to 'somewhere else' that had  all those design discusions/details etc
16:50:34 <bcoca> also, specially since 2.9 .. core 'features' are a lot less and a lot more manageable, the majority of dev was always modules
16:50:37 <samccann1> but as bcoca said, we don't have that 'somewhere else' today
16:50:48 <samccann1> and we don't have those 50 adhoc additions even in the roadmap.
16:51:07 <bcoca> samccann1:  consider that a lot of 'features' come from 3rd parties and never planned by us
16:51:11 <bcoca> example:
16:51:16 <bcoca> throttle keyword
16:51:37 <bcoca> part of base lanaguage, but was totally 'unforseen' by core team and still we added it (solved many issues)
16:52:04 <samccann1> ok this has been an interesting discussion for sure!
16:52:18 <samccann1> we have 8 minutes left though... so time to open the floor maybe?
16:52:31 <bcoca> 2 of my conflicting meetings moved (one not utc, other ended early ...)
16:53:15 <felixfontein> samccann1: btw, which version of antsibull-docs is used for the 7.0.0rc1 docs?
16:53:40 <bcoca> https://github.com/ansible/ansible/compare/devel...bcoca:ansible:controller_argspec  looking for 'lanaguage' for docs for 'required_X' and other rules that now do not make it for docs but are in argspec
16:53:56 <samccann1> felixfontein: pretty sure we are 1.7.1 still
16:54:03 <bcoca> bottom of file has examples
16:54:24 <samccann1> but matt said it was up to us if we want to allow 1.7.x in the docs build but not in the CI containers.
16:54:31 <felixfontein> samccann1: would it be possible to switch to 1.7.3 for 7.0.0? broken docs like http://docs.testing.ansible.com/ansible/7/collections/community/docker/docker_container_module.html#attributes are not really nice
16:54:33 <samccann1> felixfontein: do we need an update before GA?
16:54:53 <felixfontein> (see `Action groups: |antsibull-internal-nbsp|
16:54:55 <felixfontein> `)
16:54:58 <briantist> just random other example of a relatively new (useful!) feature, that affects docs, but has no docs: attributes
16:55:02 <samccann1> felixfontein: yes we can
16:55:19 <briantist> I messed mine up and still have to fix them: https://github.com/ansible-collections/community.hashi_vault/issues/325
16:55:23 <bcoca> briantist: but that was planned ... looooongtimeago
16:55:36 <briantist> ok, but implemented recently
16:55:41 <briantist> (ish)
16:55:54 <bcoca> yes, also still not 100% done (controller side argspec will add to that_
16:56:09 <samccann1> briantist: yeah we should have docs for that for sure. Is there anything written down anywhere about these that we can use to flesh out the docs?
16:56:53 <briantist> I used this partially: https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/doc_fragments/action_common_attributes.py#L11
16:56:54 <briantist> and also this: https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/include_role.py
16:56:59 <felixfontein> briantist: that will have to wait for at least 7.1.0 then, since likely the next release will be 7.0.0 (assuming there are no huge blunders in 7.0.0rc1) and that will have the same collection versions as 7.0.0
16:57:26 <briantist> felixfontein: put in a bunch of PRs to add attributes recently, and I learned from those as well
16:57:47 <briantist> since he implemented a lot of it in the tools, he had some more knowledge about how they were supposed to be used :p
16:58:01 <briantist> felixfontein: what will have to wait for 7.1.0?
16:59:54 <felixfontein> briantist: a new c.hashi_vault release
17:00:27 <samccann1> issue to track documenting attributes - https://github.com/ansible/ansible/issues/79384
17:00:54 <samccann1> if you have other hints on how to do this please add to that issue
17:01:13 <samccann1> felixfontein: are you up for creating the PR to bump antsibull-docs to 1.7.3?
17:01:33 <bcoca> briantist: also about attributes, they are NOT limited to existing ones, they can be used by authors to define/note quirks about their plugins that create/dont follow diff norms
17:01:36 <briantist> if I make that change with no other functional changes, I would release it as `x.y.1` which would at least have the `devel` docs updated; I'm not too concerned about when it gets into `latest`, otherwise I would've rushed to fix it
17:01:42 <samccann1> then I can beg a backport w/ the understanding the CI won't be updated in stable-2.14... probably ever
17:02:05 <briantist> bcoca: yes! you mentioned tha tpreviously, and I'm very interested in that, but have 0 examples on how to do it
17:02:51 <felixfontein> briantist: simply add one with a new name ;) we might need to come up with best practices for such attributes though
17:03:36 <bcoca> s/best practices/advice/\
17:04:15 <briantist> the "sub" fields seem like they have different norms about which are required and how they are used... or did I imagine that? anyway I'll experiment with it when I have time. Advice is helpful..
17:05:24 <samccann1> ok we're five minutes over... anythhing else before we close out?
17:06:43 <samccann1> #endmeeting