14:30:16 <acozine> #startmeeting Docs Working Group aka DaWGs
14:30:16 <zodbot> Meeting started Tue Mar 10 14:30:16 2020 UTC.
14:30:16 <zodbot> This meeting is logged and archived in a public location.
14:30:16 <zodbot> The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot.
14:30:16 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
14:30:16 <zodbot> The meeting name has been set to 'docs_working_group_aka_dawgs'
14:30:38 <acozine> who's around?
14:30:44 <dmellado> o/
14:30:51 <acozine> #chair dmellado
14:30:51 <zodbot> Current chairs: acozine dmellado
14:31:34 <acozine> agenda for today includes anything folks here want to chat about, plus https://github.com/ansible/community/issues/521#issuecomment-594019765
14:31:48 <acozine> cbudz: samccann you two around?
14:32:12 <samccann> i'm here!
14:32:26 <samccann> sorry had to step away for a sec but i'm back
14:32:44 <acozine> #chair samccann
14:32:44 <zodbot> Current chairs: acozine dmellado samccann
14:33:29 * acozine scrolls back and reads conversation from earlier
14:33:44 <samccann> ok while you scroll, I'll attempt some summary info notes
14:33:56 <samccann> #Topic Release Notes and Collection-level documentation
14:35:14 <samccann> #info network team proposing to use https://docs.openstack.org/reno/latest/ to gather collection-level release notes.  This is an .rst tool that can work with sphinx to publish to a docsite
14:35:54 <samccann> #info Galaxy's current plans are for .md only, and not for complicated documentation (just what is in the collection /docs folder as a flat display in the future)
14:36:23 <cbudz> sorry I have a conflict with aaS docs meeting today
14:36:55 <samccann> #info along with release notes, we also have the issue of each collection will need its own 'docsite' equivalent for anything more complicated (such as these release note fragments, porting guide details,  complete user or developer guides etc)
14:37:48 <acozine> cbudz: too bad, but understood
14:38:33 <samccann> #info each collection can already have its own docsite, but what can we do for the collections the Ansible team creates? One proposal - do what docs.openstack.org does - publishes each project as a subdir under that url.
14:39:01 <samccann> #info - unsure how we would decide which collection-level docs get to piggyback on docs.ansible.com, and which have to roll their own docsite
14:39:15 <acozine> so our first goal with collections docs is to maintain the equivalent of the existing (2.9/latest) module documentation in the 2.10/collections ecosystem
14:39:16 <samccann> phew. ok that's what I remember from the discussion.
14:39:43 <acozine> samccann: thank you!
14:40:07 <dmellado> samccann: thanks for summarizing all my proposals in a sane way xD
14:40:40 <samccann> heh
14:40:52 <samccann> oh and one more
14:41:15 <samccann> #info network team also will gate PRs with zuul to ensure a correct base level of docs
14:41:20 <samccann> (or something like that?)
14:41:50 <dmellado> yeah, basically that means the docs will be treated as code, so PR changing code would be matched there
14:41:58 <dmellado> basically, and using sphinx again
14:42:05 <dmellado> (disregard the rst-md for now)
14:42:35 <dmellado> sphinx-build -W -b html doc/source doc/build/html
14:42:44 <dmellado> so they ensure the actual documentation can be built
14:42:53 <dmellado> -W changes warnings to error as well
14:42:59 <acozine> ah, that's good
14:43:10 <dmellado> so we can actually test that no doc PR is breaking anything
14:43:20 <acozine> Sphinx's ideas about what should be an error and what doesn't have to be an error are sometimes weird
14:43:44 <dmellado> acozine: I assume (not reallyu 100% sure) that that can be tweaked at conf.py
14:44:15 <acozine> will the network modules still have the usual module documentation within each python module?
14:44:17 <dmellado> nevertheless, that's how it's done on openstack, and as there are a *lot* of projects IMHO that can be mapped to cllections
14:44:37 <dmellado> the metadata you mean?
14:44:59 <dmellado> I'll need to check that out, but I assume so
14:45:02 <samccann> yeah afaik all the module/plugin level docs are the same for the network collections
14:45:15 <dmellado> for now I want to have that for releasenotes at least
14:45:20 <samccann> i think the issue is they are ahead of us in terms of what they are looking for from docs support so to speak
14:46:00 <acozine> collection-level docs, right?
14:46:06 <dmellado> yep
14:46:11 <acozine> "how to use all this content together to achieve your goals"
14:46:23 <acozine> that is awesome
14:46:29 <dmellado> but in any case I'll roam around here and will ask/provide info ;)
14:46:29 <samccann> heh yep. tho starting with release notes it seems.
14:46:45 <dmellado> now that I got my bouncer back online xD
14:47:36 <acozine> so is there a higher-level index for openstack docs like https://docs.openstack.org/kuryr/latest/?
14:48:26 <samccann> https://releases.openstack.org/train/index.html
14:48:32 <acozine> wow, that is a LOT of documentation
14:49:09 <acozine> is that all community-maintained?
14:49:10 <dmellado> yeah, it's a lot but it maps to the subprojects one, which I assume we could treat as collections-like
14:49:11 <samccann> it is!
14:49:12 <dmellado> it is
14:49:19 <dmellado> there's a concept, though
14:49:31 <dmellado> which is PTL/maintainer (even upstream)
14:49:38 <dmellado> that I wonder if we should also somehow adopt
14:49:41 <samccann> yeah seems projects are like collections in that sense...
14:49:49 <dmellado> that means that if you have a collection, you ought to abide to some rules
14:49:56 <samccann> as in a docs maintainer for each project (collection?)
14:49:57 <dmellado> and that implies delivering some docs and release notes
14:49:59 <dmellado> yep
14:50:34 <samccann> yeah we have that in mind for certified collections for sure. It won't be extend to community level collections tho.. more of an 'opt in' so to speak on what they do with docs
14:50:54 <dmellado> even if it's some 'opt-in'
14:51:10 <dmellado> we can say it's 'recommended that you provide documentation for your collection in this and that way'
14:51:21 <samccann> yeah that's the plan
14:51:44 <dmellado> i.e. check this for openstack and release notes and so
14:51:46 <dmellado> https://governance.openstack.org/tc/reference/pti/python.html#release-notes
14:51:49 <samccann> the empty part of the plan tho, is where to display those docs. And so far, it's make your own docsite if it's beyond just a handful of simple .md files
14:52:48 <samccann> #info openstack has some docs recommendations/governance, including release notes - https://governance.openstack.org/tc/reference/pti/python.html#release-notes
14:53:13 <acozine> I'm still wrapping my head around the OpenStack docs model - the "service projects" are the equivalent of collections?
14:53:18 <samccann> #info full openstack docsite - https://releases.openstack.org/train/index.html
14:53:46 <samccann> they are subprojects.  We are just saying what they do for sub project, we might be able to do for some set of collections
14:53:57 <dmellado> acozine: samccann I know this is overkill
14:53:58 <acozine> gotcha
14:53:59 <dmellado> https://docs.openstack.org/doc-contrib-guide/
14:54:07 <dmellado> but that is the docs contributor guide ^^
14:54:32 <dmellado> what I was thinking is that if we can allow every collection to handle their own doc but somehow get that part and publish it ourselves
14:54:36 <dmellado> that'd be cool
14:54:47 <samccann> #info docs contributor guide for openstack - https://docs.openstack.org/doc-contrib-guide/
14:54:51 <dmellado> I'm not sure about that part in openstack, though, but can ping people about it
14:54:59 <acozine> nice! we have a lot of this material written for the old docs pipeline, but not for the NWO
14:55:17 * acozine takes self to task for acronyms
14:55:24 <dmellado> NWO?
14:55:28 <samccann> so are each openstack project int their own github repo?
14:55:30 <bcoca> new world order
14:55:31 <acozine> NWO == New World Order, otherwise known as the Collections Ecosystem
14:55:32 <samccann> new world order
14:55:39 <samccann> HAHA welcome bcoca !!
14:55:43 <dmellado> hiya bcoca
14:55:44 <bcoca> aka life after 'the exodus'
14:55:46 * bcoca waves
14:55:48 * bcoca hides
14:55:52 <acozine> #chair bcoca
14:55:52 <zodbot> Current chairs: acozine bcoca dmellado samccann
14:55:59 <acozine> you can run, but you can't hide
14:56:07 * bcoca runs
14:56:16 <samccann> can't run fast enough to not be hit in the back w/ a chair!
14:56:30 <dmellado> for a second I thought about a dystopic reality after roconavirus, pretty much like in fallout series xD
14:56:36 <samccann> heh
14:56:39 <dmellado> s/rocona/corona
14:56:55 <bcoca> samccann: feeling a bit violent today?
14:57:04 <samccann> every day bcoca ...every day
14:57:15 * bcoca takes 3k steps back
14:57:26 <samccann> i just don't always get the opportunity to toss furniture in a work-acceptable manner!
14:57:34 <bcoca> dmellado: corona is just a sars variant, nothing to worr...
14:58:21 <samccann> meanwhile dmellado: is every openstack project its own github repo?
14:58:25 <acozine> what next steps can we take to explore the possibilities of an openstack-like docs site?
14:58:31 <dmellado> samccann: as a matter of fact, yeah
14:58:40 <dmellado> they're hosted on gitea, but gihub is a mirror
14:58:43 <samccann> ok cool.  makes the analogy hold well
14:59:01 <acozine> is the source of the openstack docs also in rST?
14:59:05 <dmellado> it is
14:59:12 <acozine> better and better
14:59:21 <samccann> so steps forward:
14:59:40 * gundalow waves
14:59:45 <samccann> 1 - evaluate the technical side (aka explore, read, ask questions, think deep thoughts)
15:00:05 <samccann> 2 - get a wider audience looking at this idea to see if they agree/approve
15:00:27 <samccann> 2 - determine what subset of collections get to be on docs.ansible.com if everyone agrees it's a spiffy idea
15:00:39 <samccann> daaag nam it!
15:00:48 <dmellado> s/2/3 xD
15:00:53 <samccann> (extra a so as not to ping a contributor)  and yep heh
15:00:54 <acozine> heh
15:00:58 * bcoca has joke about 'off by one errors'
15:01:07 <samccann> heh
15:01:13 <dmellado> I will create a WIP patch for the reno thing, which can be seen as a sample
15:01:18 <acozine> #chair gundalow
15:01:18 <zodbot> Current chairs: acozine bcoca dmellado gundalow samccann
15:01:26 <gundalow> Thanks :)
15:02:06 <samccann> #agreed next steps - review how openstack does all this technically, and broaden the discussion to get approval/buyin etc
15:04:24 <samccann> gundalow: you got thoughts on all the above?  (general idea of using the openstack docs model to publish some subset of collection-level docs, including release notes, on docs.ansible.com?)
15:04:34 <acozine> samccann: can you make sure that "follow up on OpenStack docs model discussion" gets onto next week's agenda?
15:04:52 <samccann> ok
15:05:11 <samccann> #action samccann to add 'followup on openstack docs model' to next week's agenda
15:05:13 <samccann> :-)
15:05:19 <acozine> oooh, you're good!
15:05:46 <samccann> i should make it a weekly goal to use a new hashtag irc meeting thingie every week
15:05:53 <dmellado> xD
15:06:02 <samccann> thingie... cuz i is a riter
15:06:10 <acozine> heh
15:06:22 <gundalow> samccann: No thoughts of the top of my head, though you said, writing what we have and what options are sounds like a good start
15:06:43 <samccann> kewl. At least it didn't blare a big red flag yet !
15:07:16 <samccann> should I start a proposal for this in github to track? (and if so, on ansible/ansible or ansible-collections??)
15:07:47 <dmellado> if it helps tracking it, deff
15:07:56 <acozine> good question . . . on ansible-collections might make more sense
15:08:09 <acozine> we'll have to get in the habit of looking there for issues
15:08:36 <samccann> actually, ansible-collections is like ansible in github.. it's the toplevel... thingie :-)  Not sure proposals are tied at that level vs at the repo level?
15:08:47 <gundalow> Feel free to add to https://github.com/ansible-collections/overview/issues
15:09:00 <gundalow> and we can add it to https://github.com/orgs/ansible-collections/projects/1
15:09:00 <acozine> having a proposal/issue open will let us gather feedback more widely
15:09:16 <samccann> ok thanks gundalow
15:09:54 <acozine> cool
15:10:13 <acozine> for a second I thought /overview was some kind of GitHub magic "across all repos" thing for orgs
15:10:13 <samccann> #action samccann to create proposal for this openstack-like docs on https://github.com/ansible-collections/overview/issues and add it to https://github.com/orgs/ansible-collections/projects/1
15:11:07 <samccann> ok is there anything else we want to add to this convo before we move on?
15:12:22 <samccann> ok will now...
15:12:28 <samccann> #topic Open Floor
15:12:41 <samccann> anyone have something they want to bring up/discuss on the docs?
15:12:57 <dmellado> I guess I already did, sorry for taking a bit over xD
15:14:19 <samccann> no worries! it's been a conversation we needed to have, and you even came with a potential solution/strategy!
15:15:28 <acozine> dmellado: that's what this meeting is for!
15:15:44 <samccann> should we shift to docs issues triage then?
15:15:59 <acozine> sounds good to me
15:16:59 <acozine> #topic issues triage
15:17:43 <acozine> full list of issues labelled `docs`: https://github.com/ansible/ansible/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Adocs
15:18:04 <acozine> we'll start at page 9 (oldest issues)
15:18:42 <acozine> we've looked at the last three . . . so
15:18:59 <acozine> https://github.com/ansible/ansible/issues/19478
15:19:33 <samccann> #link https://github.com/ansible/ansible/issues/19478
15:20:38 <acozine> I think this comment is the actionable bit: https://github.com/ansible/ansible/issues/19478#issuecomment-297431456
15:21:14 <acozine> there's a config option for whether or not modules are aware of the user's locale settings
15:21:24 <samccann> this is the currentcommand module docs - https://docs.ansible.com/ansible/latest/modules/command_module.html#command-module
15:22:33 <samccann> nothing in the command module docs mention that config option. Is the fix to just add that as a note?
15:23:13 <acozine> I can't find any documentation of that config option anywhere
15:23:56 <acozine> the only way to find it would be to use `ansible-config`
15:24:57 <acozine> should we treat this as specific to the command module? or is it more broadly relevant?
15:26:21 <samccann> well I think the default changed to false right around when this issue was created. So I don't think we need to change the command module at all
15:26:38 <samccann> but if we don't document that option anywhere, that's problematic. trying to google for it now
15:28:16 <samccann> the plot thinkens
15:28:37 <samccann> DEFAULT_MODULE_SET_LOCALE was removed in 2.8 near as I can tell.
15:28:50 <samccann> at least it exists in the 2.7 docs but not the 2.8 docs.
15:30:05 <samccann> possibly related - https://github.com/ansible/ansible/issues/38608
15:31:57 <samccann> ok that was a false alarm... it just has the deprecation warning in an unrelated issue. But it does say that each module handles this on their own now.
15:32:30 <acozine> good sleuthing samccann
15:32:57 <acozine> if we want belt-and-suspenders coverage we could try to test the original behavior
15:33:56 <samccann> or we could close. :-)
15:33:59 <acozine> heh
15:34:36 <acozine> sure - let's put a note on it saying the config setting was removed in 2.8 and unless we hear otherwise, we assume this issue is no longer relevant
15:34:37 <samccann> it's 3.5 yrs old, no attention, and likely works as expected now (esp since that option to enable it doesn't exist anymore.  and we are overloaded w/ work to do
15:34:43 * samccann complain complain complain
15:34:52 <samccann> ok will add that note
15:35:15 <samccann> #info the issue is likely resolved at the mentioned config setting was removed in 2.8. Close the issue
15:36:00 <acozine> I'll add a note and close
15:36:03 <acozine> and we're over time
15:36:18 <acozine> oh, nm, you said you'd add a note
15:36:23 <samccann> sorry just did that yeah
15:36:24 * acozine needs more caffeine
15:36:31 * bcoca just made new pot
15:36:33 <samccann> you get to close the next one :-)
15:36:42 <acozine> heh, let's close out the DaWGs meeting
15:36:54 <acozine> take a quick biobreak, then get back to it
15:37:04 <samccann> hey we're under 220 issues now!  woot!
15:37:13 <samccann> sounds like a plan
15:37:14 <acozine> bcoca: is there a coffee pipeline from NJ to the midwest?
15:37:42 <acozine> thanks dmellado bcoca gundalow samccann
15:37:48 <acozine> see everybody next week!
15:37:52 <acozine> #endmeeting