16:00:11 <samccann> #startmeeting Documentation Working Group aka DaWGs
16:00:11 <zodbot> Meeting started Tue Jan 11 16:00:11 2022 UTC.
16:00:11 <zodbot> This meeting is logged and archived in a public location.
16:00:11 <zodbot> The chair is samccann. Information about MeetBot at https://fedoraproject.org/wiki/Zodbot#Meeting_Functions.
16:00:11 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
16:00:11 <zodbot> The meeting name has been set to 'documentation_working_group_aka_dawgs'
16:00:17 <samccann> #topic opening chatter
16:00:25 <acozine> o/
16:00:33 <samccann> #chair Gwmngilfen acozine
16:00:33 <zodbot> Current chairs: Gwmngilfen acozine samccann
16:00:37 <briantist> o/
16:00:46 <samccann> @room Meeting time! Who is here to talk the docs?
16:00:56 <samccann> #chair briantist
16:00:56 <zodbot> Current chairs: Gwmngilfen acozine briantist samccann
16:01:01 * acozine will be working on performance issues, so may be slow to respond today
16:01:22 * gwmngilfen-work is writing FOSDEM talks
16:02:23 * briantist just woke up, is still drinking coffee ☕
16:02:27 <samccann> andersson007_: dmsimard tadeboro cyberpear up for talking dalks today?
16:02:39 <samccann> felixfontein:  docs time?
16:02:45 <acozine> mmmm, coffeee
16:03:10 <gundalow> /me waves
16:03:23 <samccann> #chair gundalow
16:03:23 <zodbot> Current chairs: Gwmngilfen acozine briantist gundalow samccann
16:03:28 <samccann> welcome welcome!
16:04:14 <samccann> Official agenda is at https://github.com/ansible/community/issues/643
16:04:30 <samccann> let's start in!
16:04:32 <samccann> #topic Community guide docs
16:04:44 <samccann> #info starting a project to combine community docs from ansible/ansible and other repos where it exists. https://hackmd.io/3Cvy2N8tTfSrUzqYZmfEHA
16:05:29 <samccann> the TL;DR; is we have loads of great information on community contributions, collection contributions etc, but it's not published on docs.ansible.com today.
16:05:42 <samccann> #topic two steps - 1 - combine the information
16:05:45 <samccann> dagnammit!
16:05:51 <samccann> #undo
16:05:51 <zodbot> Removing item from minutes: <MeetBot.items.Topic object at 0x7fb5ef31de80>
16:06:11 <samccann> #info step 1 - combine the info
16:06:23 <samccann> #info step 2 - publish (possibly from different repos)
16:06:50 <felixfontein> o/
16:06:51 <samccann> So the proposal is we publish everything to docs.ansible.com/ansible, but we may pull the collection contributor info from a separate repo
16:07:12 <samccann> #chair felixfontein
16:07:12 <zodbot> Current chairs: Gwmngilfen acozine briantist felixfontein gundalow samccann
16:08:03 <gundalow> Would be great to get feedback from folks on this. It going to alter how a lot of future work is done
16:08:48 <briantist> in a way, we already do this via collections that are included in the ansible package (which can include arbitrary documentation in the form of a "docsite"). Maybe, we can have a separate "docs only" category of "inclusion" that isn't related to the ansible package, but is only related to the "one true" docs build
16:09:28 <samccann> yeah I figure this is the start of something like that.
16:09:45 <samccann> from the user/reader perspective, all the info is where they are used to finding it etc. And existing search will find it.
16:10:10 <acozine> reading the comments in the HackMD, I see that we used to have options 1-4 - it looks like the "Old, elminated options" are the ones that were previously options 2 and 3?
16:10:31 <samccann> oh sorry. Yeah I cut out the 2 that didn't make much sense
16:10:39 <acozine> gotcha
16:10:45 <samccann> they were variants of 'spin up a different docsite'
16:10:50 <acozine> okay, I'm following this now
16:11:01 <samccann> sorry about that, I forgot about the comments lol
16:12:42 <acozine> gundalow: what kind of feedback are you thinking? and what's the timescale?
16:13:44 <samccann> on timescale, I'd like to start 'merging' what I can asap.  so the image here - https://hackmd.io/3Cvy2N8tTfSrUzqYZmfEHA#Options
16:14:19 <samccann> starts to happen. I think I can make a 'generic' community guide fairly easily. and potentially a 'core contributor' guide as all that is in ansible/ansible.
16:15:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:15:09 <samccann> I can then 'make' a collection contributor guide in the other repo where the files already exist....
16:15:27 <samccann> (aka plenty of work to do on the words while we decide on the location of the source files)
16:15:31 <gundalow> acozine: Both good questions. I think it would be great if we could get agreement soon (Feb?)
16:15:59 <gundalow> I'm not sure how widely we need to discuss this and get feedback from
16:16:56 <acozine> Given recent discussions about the steering committee, I've been thinking about how to draw feedback from a wider group of folks
16:16:59 <samccann> I'm trying to think about the impact on docs contributors with this. With 'magic coding' we could still have an edit on github button, and add an 'open an issue' button on each page. That's similar to what felixfontein has working for collections today in a PR.
16:18:14 <acozine> we didn't do a full docs user survey last year, could we do a quick "where would you expect to see documentation about contributing to collections?" survey?
16:18:53 <samccann> acozine: I'm not sure why? they would still see the documentation on docs.ansible.com/ansible. Or are you thinking collections people expect to see it someplace else?
16:19:26 <acozine> ah, right, both remaining options have all docs on docs.ansible.com . . .
16:19:35 <samccann> yeah.
16:19:46 <acozine> I'm not sure wide feedback is useful, then
16:20:01 <acozine> at most the difference would affect collection maintainers, that's not a huge group
16:20:14 <acozine> I mean, we should definitely still ask
16:20:38 <acozine> but it can be a quicker turnaround
16:20:50 <samccann> ok cool. I think we do need feedback on whether the 'insert magic code here' stuff is feasable, and the impact if any on core (ci tests etc). Part of the reason to move these docs to another repo is to lower (or at least not add onto) the core repo burden
16:21:28 <samccann> Whom do we ask for feedback? I can (or possibly did? will have to search) make this a community topic proposal and can put it in the bullhorn. Where else? the devel mailing list?
16:22:25 <gundalow> community-topic, Bullhorn, reddit
16:24:36 <gwmngilfen-work> >  make this a community topic proposal
16:24:36 <gwmngilfen-work> I don't see it in https://github.com/orgs/ansible-community/projects/2/views/1?filterQuery=doc
16:24:36 <samccann> #action @samccann to turn community docs idea into a community-topic proposal and share on bullorn and reddit
16:24:42 <gwmngilfen-work> just fyi
16:24:58 <samccann> thanks. must have dreamt I did it already...
16:25:02 * samccann frightened of her own dreams now
16:25:20 <samccann> ok we have another interesting new topic if we are winding down on this one?
16:25:39 <acozine> sounds good
16:25:57 <acozine> (or was that a request for another interesting new topic?)
16:26:03 <samccann> #topic Better changelog guidelines
16:26:14 <samccann> heh no I have one queued up
16:26:26 <samccann> tho interesting topics ALWAYS welcome here! makes things more fun!
16:26:29 <samccann> #info We had some feedback to create better guidance for developers on what to include in changelog fragments - https://hackmd.io/ZdymdeUSQNeM0hMjsn7vig
16:28:02 <briantist> do we need better guidance than what's at this page? https://docs.ansible.com/ansible/latest/community/development_process.html#creating-a-changelog-fragment
16:28:06 <bcoca> samccann: git commits: the 1st one is normaly the 'summary' of the PR, so that one at least should be descriptive (others will get merged or removed by merger)
16:29:19 <samccann> briantist: yeah the request came from @webkinjaz
16:29:34 <samccann> and I'm sure I have that irc name wrong but can't remember his real name here
16:29:48 <acozine> Sviatoslav
16:29:56 <samccann> But the gist of it is - git commit is great for developers, but some developers are writing changelog fragments in a similar way
16:30:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:30:19 <samccann> yeah I meant his irc nick because what I typed isn't showing up
16:30:26 <acozine> oh, erm
16:30:59 <acozine> no idea
16:31:20 <samccann> So there is debate - who are the changelogs for - other developers, or end users (or both) and do we need to consider better guidance on what to include/what not to include. etc. The idea is to Deep Thought on this and then maybe help set a trend for other projects as well
16:31:28 <samccann> this is just the start of the discussion.
16:32:00 <felixfontein> changelogs in collections and ansible-core are primarily for users, not for developers
16:32:17 <gwmngilfen-work> I don't think @webknjaz is in this room
16:32:19 <felixfontein> some are also specific for developers, but most are not
16:32:40 <bcoca> depends on changelog, many are about api or internal logic
16:32:46 <briantist> I don't know if this is technically on topic, but do we still want to expect that the changelog fragment include the PR number? I get that in ansible/ansible it made sense (maybe still does) for organizing, when all changes were done there. But there's no technical requirement around it. Some collections don't enforce it or seem to care. But it is still in the guidance. I mostly ask because it necessarily requires an
16:32:46 <briantist> additional commit after the PR is created unless you're good at predicting the next number.
16:32:47 <bcoca> others are for purely user facing features
16:33:24 <bcoca> briantist: the # was initially of the 'issue' that the PR was fixing, dont know when that got reversed adn required tardis to get right
16:33:29 <felixfontein> bcoca: changelog entries on such topics are for developers. but at least in collection world, most changelog entries are about bugs and features, and thus should be written for users, not for developers (except if it is something developer specific, like a bug in an API)
16:33:50 <briantist> interesting context bcoca , thanks
16:34:06 <bcoca> felixfontein: since collections have module_utils, plenty of reason to think they will have dev only fragments at least once in a while
16:34:08 <samccann> yeah i think core changelogs might be a bit different in that some of them impact other developers vs the end user.
16:34:20 <felixfontein> I think the docs say that the # should be for the issue if there exists one, and for the PR if there is no issue
16:34:40 <samccann> #info some ansible-core changelogs impact other developers. Most/all collection changelogs impact end users
16:34:46 <felixfontein> bcoca: true. I'm just saying that *most* changelog fragments will not be of that kind :)
16:35:01 <briantist> felixfontein: it doesn't mention issue now: `The file name should include the PR number and a description of the change`
16:35:14 <samccann> felixfontein: yeah that's what I was thinking. in the ideal world, the changelog points to the issue.
16:35:40 <bcoca> briantist, felixfontein i think we should just update it to reword as felix expressed vs current doc
16:36:30 <felixfontein> actually the examples on changelog entry format show that the link *inside* the fragment should be for the issue if available, and otherwise for the PR
16:36:42 <samccann> yeah I'm in favor of pointing to the issue in the changelog, where it exists. Any other opinions on that one?
16:36:54 <briantist> bcoca: makes sense to me.. though I think I might stop enforcing any number at all in my (tiny) collection
16:37:15 <bcoca> briantist: most of core changelogs ignore that requirement
16:37:22 <briantist> right the link inside the changelog, as felix pointed out, already has that guidance, I was only referring to the file name
16:37:42 <felixfontein> briantist: I usually only care about the fragment's content; having the issue # or PR # in there is way more important to me than the filename (which I usually ignore anyway :) )
16:37:45 <bcoca> also many PRs fix more than one issue
16:37:54 <briantist> felixfontein: bcoca: well that best answers how required it is then :)
16:38:15 <briantist> ok I don't want to derail further with this little aside, thanks for indulging me :)
16:38:17 <felixfontein> bcoca: you can put multiple #s in the filename, and multiple links in the content ;)
16:39:14 <samccann> ah I think including a number in the filename is useful only when someone has to go back in and change it, right?
16:39:17 <bcoca> 345345_097654_345456_23432_iforgotwhatthisfixesatthispoint.yml
16:39:25 <samccann> like they messed up the fragment so need to edit it?
16:39:57 <bcoca> samccann: we tend to find it via the commit, idk anyone that uses PR/.issue # to find em
16:40:12 <samccann> me
16:40:22 * bcoca sits corrected
16:40:26 <samccann> lol. when I attempted to edit changelogs. it go way out of hand way too fast so gave up
16:41:36 <samccann> so i'm not picky on the filenaming convention. I like having a link to the issue because that could help both the user and the developer find out more info if it's important to them
16:42:32 <samccann> Though as bcoca said, some PRs fix multiple issues.
16:43:15 <bcoca> some issues require mulitple PRs!
16:43:35 <bcoca> though ~ 70% is one-to-one in core
16:43:45 <samccann> ok so pulling this back on track a bit...lol
16:44:16 <samccann> Since @webkinjaz isn't here, maybe I turn this into an async topic on community-topics and garner ideas there?
16:44:32 <felixfontein> sounds good to me
16:45:01 <remindbot[m]> @smccann:matrix.org cyb-clock chimes Fifteen exciting, thrilling minutes have slipped by whilst we plot to take over the universe, one doc at a time!
16:45:06 <samccann> #action  @samccann to turn changelog guidance into community-topic to widen discussion/feedback
16:45:13 <samccann> ok moving on
16:45:27 <samccann> #topic DocTools
16:45:43 <samccann> #info simplified module tables are up on devel! https://docs.ansible.com/ansible/devel/collections/community/general/aix_lvol_module.html
16:46:12 <samccann> felixfontein: if you can get me a better example or two (that show the links etc) I can post out to 'the usual places' for feedback
16:46:16 <acozine> w00t! nice work!
16:46:29 <briantist> cool!
16:47:00 <samccann> yes!! woot!
16:47:24 <felixfontein> ah, I kind of assumed the build failed since it still says 'Jan 10, 2022' at the bottom - I never tried to actually make my browser window narrower :)
16:48:18 <acozine> it's Jan 10 a lot longer here than where you are ;)
16:48:33 <felixfontein> samccann: re links, I would probably use several ones: one with a module which has very few suboptions, one to a deeply nested one, and one for a plugin
16:48:44 <felixfontein> (with some ini/env/vars/... options)
16:49:13 <felixfontein> acozine: looks like :D
16:49:18 <felixfontein> when does jenkins usually builds devel?
16:49:25 <samccann> ok just post them here when you get a list felixfontein
16:49:38 <samccann> last build was 2:30am today (by jenkins time)
16:49:50 <samccann> and it passed.
16:49:53 <felixfontein> lol. what's jenkins time? ;)
16:50:01 <samccann> I wish I knew lol
16:50:13 <felixfontein> :)
16:50:13 <samccann> I think its ET (my timezone).
16:50:31 <samccann> I don't know what sets 'last updated'
16:50:37 <briantist> I do believe Jenkins displays times in your zone, in the browser
16:51:31 <samccann> ah ok. So it may be catering to my timezone in the browser, but whatever sets the 'last updated' time could be say, west coast or  something? not really sure what controls that but we can see what it says later today or tomorrow.
16:51:49 <felixfontein> samccann: https://docs.ansible.com/ansible/devel/collections/community/crypto/acme_certificate_module.html#parameters https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/hashi_vault_lookup.html#parameters https://docs.ansible.com/ansible/devel/collections/cisco/ios/ios_bgp_address_family_module.html#parameters
16:52:26 <samccann> #info good samples of this https://docs.ansible.com/ansible/devel/collections/community/crypto/acme_certificate_module.html#parameters  and https://docs.ansible.com/ansible/devel/collections/community/hashi_vault/hashi_vault_lookup.html#parameters and https://docs.ansible.com/ansible/devel/collections/cisco/ios/ios_bgp_address_family_module.html#parameters
16:52:44 <felixfontein> that would be 7:30 UTC, which is 8:30 my time (right now)
16:52:47 * acozine has to step away - good to "see" everybody!
16:52:55 <samccann> thanks acozine!
16:52:59 <felixfontein> I don't remember when exactly I looked this morning, might have been before or after that
16:53:07 <felixfontein> bye acozine!
16:53:14 <acozine> #unchair acozine
16:53:14 <zodbot> Current chairs: Gwmngilfen briantist felixfontein gundalow samccann
16:53:32 <samccann> ok we have five minutes left so gonna do  a quick open floor
16:53:33 <samccann> #topic Open Floor
16:53:44 <samccann> Now's the time to bring up anything on your mind we haven't covered
16:54:21 <briantist> The docs build github stuff has been moved to its own repo: https://github.com/ansible-community/github-docs-build
16:54:31 <samccann> favorit PRs or issues you want to bring up
16:54:45 <briantist> `community.hashi_vault` and `community.docker` are using it so far, issues and discussions have been files
16:54:47 <briantist> filed*
16:54:49 <samccann> #info The docs build github stuff has been moved to its own repo: https://github.com/ansible-community/github-docs-build
16:55:08 <briantist> felixfontein: has graciously agreed to help maintain it, where his limited time permits (thank you!)
16:55:18 <briantist> and has already made several useful contributions
16:55:26 <samccann> #info this allows collection owners to create collection docs during the PR to validate they work
16:55:39 <samccann> this is great stuff!
16:55:57 <briantist> it also allows for other scenarios, like if you just want to make a simple job that validates docs will build (without doing anything with the docs themselves)
16:56:09 <briantist> or if you wanted to make a job that builds the docs for multiple collections
16:56:36 <briantist> it's split in a such a way you can put together different scenarios
16:57:08 <samccann> cool.  we should get this documented lol
16:57:27 <briantist> yes! I have started documentation on it too, in the repo's wiki: https://github.com/ansible-community/github-docs-build/wiki
16:57:35 <briantist> I have lots more to write on that :)
16:57:56 <samccann> #info documentation on this feature just starting but is at https://github.com/ansible-community/github-docs-build/wiki
16:58:00 <samccann> woot! thanks!
16:58:23 <samccann> about a minute left.. .anything else folks want to talk about?
16:59:16 <briantist> that's all from me
16:59:42 <samccann> ok thanks everyone!
16:59:46 <samccann> #endmeeting