14:31:24 #startmeeting Docs Working Group aka DaWGs 14:31:24 Meeting started Tue Nov 24 14:31:24 2020 UTC. 14:31:24 This meeting is logged and archived in a public location. 14:31:24 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 14:31:24 Useful Commands: #action #agreed #halp #info #idea #link #topic. 14:31:24 The meeting name has been set to 'docs_working_group_aka_dawgs' 14:31:30 o/ 14:31:31 felixfontein: hi! 14:31:38 #chair felixfontein samccann 14:31:38 Current chairs: acozine felixfontein samccann 14:31:44 I will see you all next week. I am on PTO for the holidays :) 14:31:47 #topic opening chatter 14:31:58 have a restful week lmodemal 14:32:08 and happy Thanksgiving! 14:32:16 lmodemal: enjoy 14:32:17 lmodemal: enjoy your PTO! :) 14:32:21 acozine: thanks! Happy Thanksgiving! 14:32:24 #chair gundalow 14:32:24 Current chairs: acozine felixfontein gundalow samccann 14:32:27 thank you felixfontein! 14:32:36 thanks gundalow! 14:32:52 I'm in training at the moment, though I'll skim here occasionally 14:33:08 today's agenda: https://github.com/ansible/community/issues/521#issuecomment-729054696 14:33:17 gundalow: okay, we won't distract you too much 14:33:23 who else is around? 14:34:09 aminvakil: andersson007_ baptistemm briantist cybette madonius mrproper persysted tremble you chatting docs today? 14:36:02 #topic slimming down the tarballs by removing docs 14:36:06 this one is quick 14:36:13 hi! 14:36:37 we investigated, and discovered that removing the docs files would not make installing Ansible noticeably quicker 14:36:40 so we will not do it 14:36:43 aminvakil: hi! 14:36:45 #chair aminvakil 14:36:45 Current chairs: acozine aminvakil felixfontein gundalow samccann 14:36:51 I'm here and available 14:36:57 baptistemm: hi! 14:37:02 Hi there 14:37:03 #chair baptistemm 14:37:03 Current chairs: acozine aminvakil baptistemm felixfontein gundalow samccann 14:38:11 acozine: not at all, or very low priority (i.e. maybe somewhen in the future)? 14:38:15 so though it seemed like a nice thing to do (We can make Ansible lighter weight! We can provide an easy way for people to install just the docs!), it turns out the effort is larger than we hoped and the benefit is smaller 14:38:18 o/ 14:38:22 #chair dmsimard 14:38:22 Current chairs: acozine aminvakil baptistemm dmsimard felixfontein gundalow samccann 14:38:50 I guess the main benefit now is that you could get .html docs 14:39:02 felixfontein: I'd say very low priority 14:39:07 acozine: is the methodology for the tests as well as the results available ? 14:39:20 we can certainly do it in future 14:39:55 dmsimard: good question, let me dig back and see if I can find the stats 14:40:21 acozine: good, so in case someone asks, we can always say "if you volunteer to implement it..." ;) 14:40:24 ok, this is in part for personal curiosity as I'd like to get a better grasp on the install performance regression from 2.9 to 2.10 14:40:56 felixfontein: heh, yep 14:41:07 So as she's digging up info, what i recall is that the size difference is somewhere around 5% less if we pull out all the docs 14:41:08 dmsimard: it's probably mostly "more content => slower" 14:41:09 thanks for looking, can wait until later for the data 14:41:32 dmsimard: rst files are 983 out of 32624 files and 25MB out of 225MB 14:41:42 And speed increase was just a one-off quick test ( hardly scientific) but maybe shaved off a similar amount 14:42:07 compressed size difference was 28MB vs 29MB with docs included 14:42:08 shaving off tests will yield a LOT more (both in file count and size) 14:42:41 once tests have been moved to a separate tarball, docs would be interesting again. before that, not really 14:42:44 and it didn't seem worth it on the docs side to go through all that and coordinate w/ Legal to see if we are even allowed to pull source out of the source tarball for example. 14:42:45 felixfontein: yeah I'm a bit dubious, mostly because the delta between 2.9 and 2.10 shouldn't be /that/ significant considering it mostly boils down to moving files out of tree 14:42:45 with and without docs, installing took between 90 and 100 seconds 14:42:56 no repeatable difference 14:42:58 but somewhat off topic 14:43:18 acozine: thanks 14:43:27 #info Compressed size w/o docs is 28MB vs 29MB today. Installing took 90 sec w/o docs vs 100 sec with 14:43:33 dmsimard: might be both. but yeah, someone would have to take a closer look 14:43:52 #info decision was made that it wasn't worth removing docs from the tarballs at this point. 14:43:56 samccann: thanks, having that in the minutes will be useful for Future Us 14:44:33 #topic uses of the collection `/docs/` folder 14:44:39 having gone through a bunch of old minutes, yep, most definitely it helps! 14:45:37 I know this has been on the agenda for a while 14:45:59 and i feel we should make better use of the docs folder 14:46:13 Toshio created a draft of ideas... now i just need to find it! 14:46:35 oh, excellent 14:46:37 The Powers That Be also have ideas/plans for that folder wrt Automation Hub/Galay-ng 14:46:57 dmsimard: 2.9 has 4219 files in modules/ and plugins/, while 2.10 has 7247 files (not including ansible-base's modules and plugins) 14:47:14 felixfontein: thanks, worth investigating 14:48:08 #info some ideas about the collections /docs folder etc - https://hackmd.io/pPeMLaFYSt2W8RAqm-ZkXA 14:49:39 * acozine has a pressing domestic issue, BRB 14:50:56 ok so Toshio created that draft doc of ideas on the collections /docs folder etc. 14:51:02 being able to link to collection docs means they are hosted somewhere 14:51:38 do we render collections docs somewhere now ? 14:51:39 Well the idea is that, in the future - the rst files in /docs would be visible within Automation Hub and Galaxy NG (I think... that's still TBD) 14:51:56 And/or we would also bring them in via the docs pipeline to docs.ansible.com 14:52:11 should have info'd that... but anyway. 14:52:48 #info the goal is to allow collection owners to write 'user guide' and more complex examples etc within the collection /docs folder and then render them in either docs.ansible.com or some future galaxy-ng 14:53:00 so we don't render them at all right now. 14:53:38 the only docs we render from collections now are the module/plugin docs 14:53:54 But we also have people using that folder for 'other things' already - like the network collections that generate module docs rst files so they can link to them from their readme. I feel like other collection owners have put other things in there too. Maybe rendering on their own docsite somewhere? That might just be my baseless worry though 14:54:43 that's a good question 14:55:20 is there any existing convention or standard for the docs/ directory at all ? 14:55:21 I would suggest that we only include docs that we are explicitly suggested to do so by the collection, for example by looking at a `docs/antsibull.yml` file and only using files references in there 14:55:25 dmsimard: no 14:55:33 dmsimard - no 14:55:52 It was created for 'future use' and we are only now grappling with what we want that future use to be 14:56:39 #info we could only include /docs that are explicitly suggested by the collection - e.g. looking ad docs/anstibull.yml file to find rst files to include 14:56:56 Thanks felixfontein - seemed like an idea worth remembering :-) 14:57:58 samccann: that file could also contain tags, or other kind of categorizations - as well as the order in which they should be referenced 14:58:34 it definitely would be good to have some validation for anchors. no idea how hard that is to do though 14:58:41 The difficulties in general - creating an RST user guide (and I'm assuming RST because that's what WE want... but Galaxy-ng only recognizes .md right now for the readme). 14:59:28 A guide is a set of files, related, crossreferenced, etc etc. So we would have to be very specific about what we can support (we being either docs.ansible.com or some future galaxy version) 14:59:37 yeah, currently Automation Hub renders rst files sort of like GitHub does 14:59:55 but in that case, it does support .rst? 15:00:08 automation hub doesnt render rst at all.. just md... and a considerable less amount than github for sure.. alas 15:00:19 but of course that's just today as all they render is the readme 15:00:53 ah, so AH also doesn't render anything in docs/? 15:01:01 samccann: I thought AH "rendered" rst without actually processing it (so no links), am I misremembering? 15:02:15 the only info I have is that it is .md only and only the readme. I could be wrong tho.. .worth asking 15:02:35 #action samccann ask galaxy team what they render today - md/rst and if they look at all in the /docs folder 15:02:36 I don't know about automation hub but galaxy does require a readme.md, won't let you publish otherwise 15:02:50 readme.rst not good enough 15:03:19 agreed. I'll gather some facts later to see if my info is woefully outdated or not 15:03:33 samccann: thanks! 15:03:46 AH is essentially galaxy-ng, right? 15:03:59 felixfontein: yes 15:04:53 felixfontein: alternative to a file which lists the files to include would be a different directory. Like docsite/ instead of docs/ 15:05:09 abadger1999: good morning! 15:05:21 do you want to be furniture? 15:05:23 (but i like the idea of someplace to put tags) 15:05:27 Sure 15:05:32 #chair abadger1999 15:05:32 Current chairs: abadger1999 acozine aminvakil baptistemm dmsimard felixfontein gundalow samccann 15:05:54 furniture, haha :D 15:06:26 abadger1999: docsite/ would make it harder to decide how and in which order to link to files from the antsibull-generated default page 15:07:08 we could say it all starts with index.rst and that links to whatever comes next and it the order listed 15:07:46 but we'd still have problems if someone wanted to put TWO or more guides in there... they'd have to create subdirs maybe with their on index.rst for those subdir rst files, etc etc 15:08:59 samccann: I like the "you must have an index.rst file that points in some way to all your other content" rule 15:09:16 they could have an index file that was a list of guides if they want multiple guides 15:09:38 Felixfontein: how are you imagining the config file addresses that? 15:11:56 abadger1999: if you don't want to allow collections to template the main index.rst, you could allow the .yml to provide a list with RST references and optional titles, and these are inserted as a list at the top. or you could allow sections (with titles), each containing lists of links 15:12:18 15:12:29 if collections use this to also document filter and test plugins and roles, having sections is very useful 15:13:09 then you can maybe add a section `Roles` at the top of https://docs.ansible.com/ansible/latest/collections/community/general/ with one entry per role (and link to the role's documentation) 15:13:22 Okay, so something like: the collection index page we generate has a section that links to a list of pages that they've listed? 15:13:45 is there a collection that would be a good "guinea pig", one where we could try these ideas out? 15:14:30 even if we just make something with lorem ipsum, it would help to have an example, I think 15:14:31 so filter and test plugins would be solved by the PR/work bcoca is doing, wouldn't it? as in once that's done, the antsibull is modified to bring it in the same as we do for all other plugin? 15:14:45 acozine: for lorem ipsum, a test collection would be best :) 15:14:47 The only issue with that which i see is that a list of links isn't very enticing 15:14:54 felixfontein: ah, of course! 15:14:58 acozine a test collection is easy.. the difficulty is getting everyone to agree on the strategy 15:14:59 samccann: yes, but no idea how long it takes until that will be available 15:15:02 heh 15:15:03 which imo has to come first 15:15:35 the same could be said about roles, and eventually playbooks 15:15:38 (clarifying the strategy has to come first.. not necessarily the test/plugin docs pr 15:16:06 #info whateve solution we have for collection /docs needs to cover roles, playbooks, as well as any other guides collectoin owners want to create 15:16:14 my brain likes to have a tangible example so I can look at it and say, 'Oh, I see how this fits together - this part works really well, could we do that part some other way?' 15:16:58 @samccann: yes. Although I'm a bit worried that we don't have a seat at that table. We should have only on the format of DOCUMENTATION strings since we have to template using them 15:17:53 does anyone know if there's actually a PR now for test/filter plugins? bcoca has been talking about that more than once, but I've never seen anything 15:18:23 abadger1999 - seat at which table? :-) the /docs folder, or how roles documentation will work? or both tables in an all you can eat docs buffet? 15:18:25 No 15:19:05 How filter and test documentation is structured 15:19:36 The docs for my impression is no one wants to touch that except us at the moment 15:19:36 I was hoping to get an idea from a PR (or branch) 15:20:15 #action - we need to get involved in how filter/test docs are structured, how the collection /docs folder works, how roles documenttion will work.. many seats... many tables 15:20:42 is there anything we can do in the next week to move this topic forward? 15:21:04 can we prioritize the list of things maybe today? 15:21:16 (no was to "is there a pr") 15:21:38 Maybe scope? 15:21:43 like which do we want to tackle/get involved with first - roles (which I think has an argspec already?) test/filter - which has ideas in someone's head) or collection /docs folder use? 15:22:25 What do we want a collection owner to be able to do? [X] include ad hoc documentation from the collection (example: guides) 15:23:03 [?] Create their own index to the autogenerated and static content 15:23:38 can you elaborate on that 2nd one? 15:24:09 I guess the main thing people want to do is inserting something at the top of the index (below the main title) 15:24:36 (though the main title 'Plugin Index' should maybe also be adjustable?) 15:24:50 Collection-level documentation 15:25:15 and documentation for all included objects (roles, filter plugins, etc.) 15:25:28 samccann: So right now we generate this index page at the toplevl of a collection: https://docs.ansible.com/ansible/2.10/collections/amazon/aws/index.html#plugins-in-amazon-aws 15:26:00 do we want collectionowners to be able to replace this? Or augment it? 15:26:11 * baptistemm dioes not participate because he is clueless 15:26:56 abadger1999: to prevent total chaos, I would prefer augment over replace 15:26:59 baptistemm: reading is also a form of participation 15:27:00 abadger1999 - augment 15:27:10 +1 for augment 15:27:49 Or a different option: We start pointing people at a different page a the toplevel for the collections and then this page, intact, is what they come to if they click on the "Included plugins" section of that page. 15:28:05 the vision imo is that as a user, I want to look at a collection (say amazon.aws) and find all the info I need to decide IF I want to use the collection, what I can do with the collection, and how to do those fancy things 15:28:09 Maybe we should make the main title the collection's name, allow some subsections, and then have a subsection called 'Plugin Index' 15:28:40 so that the plugin index is always also on the main page, and the collection name is there as well, but collections can insert things between these two 15:28:59 It feels like a user would probably be best served if there was a larger amount of information on a collection than just the list of included plugins. 15:29:12 ^^ agreed 15:29:45 +1 15:29:57 if the collection has roles, do we also add a 'Role Index'? 15:30:18 for network collections, some general "small example how to actually use this" would be useful at that level 15:30:33 acozine: imo, yes. 15:30:46 and separate from the plugin index 15:30:48 How about I make a mock up (image) of what that page could look like with extra sections? 15:31:13 f.ex. for community.routeros we added that to the README: https://github.com/ansible-collections/community.routeros/#using-this-collection but if someone looks at the plugin index https://ansible.fontein.de/collections/community/routeros/ that's a lot harder to figure out 15:31:15 that sounds great, thanks abadger1999 15:31:20 +1 so long as it's note a lot of work abadger1999 15:31:30 s/note/not/g 15:32:00 great point felixfontein - some readmes have a good bunch of info that never gets to docs.ansible.com 15:32:04 does looking how it is done on puppet help ? https://forge.puppet.com/modules/puppetlabs/stdlib 15:32:13 #info would like the collection index to have collection defined: Summary section, auto generated plugin index, links to static content section. 15:32:51 baptistemm: interesting, yes, thanks 15:33:17 it takes the readme.md but they are other folders in the github repo (likes examples/). 15:33:23 abadger1999: and auto-generated collection name and version at the top :) 15:33:56 It would probably be nice to do that immediately :-) 15:34:27 #info we should put collection name and collection version onto the collection index page (regardless of how the rest of the page is structured) 15:34:47 #info see how puppet does some of this https://forge.puppet.com/modules/puppetlabs/stdlib - with tabs for changelogs, example foler from github etc 15:36:44 we're just over one hour 15:36:50 already 15:36:59 I'd like to shoe-horn one more topic in, if I may 15:37:38 are we happy with next steps for the `/docs` folder work? 15:37:51 (in collections) 15:38:08 baptistemm: time flies when you're chatting about docs! 15:38:09 #action abadger1999 to do a slight mockup of what a new collectoin page could look like 15:38:28 samccann: thanks 15:38:28 I like the puppet labs page.... I think I like it because it's more split up. 15:38:40 they pack a LOT of information into a single screen 15:39:00 yeah, without even getting to the huge list that we're trying to push in there. 15:39:01 access to multiple versions through the drop-down, different types of documentation on panes, etc. 15:39:08 but documentation is just a single README.md 15:39:20 They also have separate tabs/pages for more info, though 15:39:56 yeah, but it's easy to see that the other info is available 15:40:00 Yep 15:40:01 I think the examples directory is just for those pulling the source code, I assume you want to expose that somewhere from a UI, right ? 15:40:13 s/from/in/ 15:41:02 Heh. Maybe. Or maybe once people have a documentation directory they'll just push examples into there. 15:41:54 (Which might be better. examples might contain raw playbooks whereas documentation might contain annotated, formatted examples with links to the reference information..... Hey, I can dream, right? ;-) 15:42:19 dreaming about what docs could do got us the excellent module docs we have today 15:42:30 annoated, formatted examples sounds better 15:42:32 changelog is equivalent https://github.com/puppetlabs/puppetlabs-stdlib/blob/main/REFERENCE.md for puppet 15:42:38 acozine: Getting back on topic. I'm satisfied we have a next step ;-) We might need to spend some time exploring different mockups before we settle on where to go next, though. 15:42:46 sounds good 15:43:06 .... with a full feature documentation 15:43:12 this is something we can chat about here in the channel between meetings 15:43:28 so if folks find other good examples, please post them! 15:43:45 #topic docs user survey 15:44:06 thanks for last week's feedback 15:44:19 it helped me focus the draft survey 15:44:37 our main goal is to find out how well our documentation is serving different groups of users 15:44:46 and whether different groups of users want different things 15:45:03 revised draft: https://hackmd.io/JemYBo_8QbqqO9cULo3rJQ# 15:45:32 Sections 1 and 2 should tell us how well our documentation is doing 15:45:45 Section 3 lets us "slice and dice" the data by different types of users 15:46:15 for example, are systems administrators happier with the docs than network administrators? 15:46:47 do folks who wish the docs were in their native language have different difficulties than folks who are happy reading the docs in English? 15:47:14 all feedback welcome 15:47:18 i also have a specific question 15:47:23 #info revised user survey draft https://hackmd.io/JemYBo_8QbqqO9cULo3rJQ# 15:47:30 if you'd like to include the survey in Bullhorn newsletter, please let me know by Tuesday Dec 1 (newsletter goes out Dec 2). 15:47:48 #info Sections 1 and 2 should tell us how well our documentation is doing 15:47:48 Section 3 lets us "slice and dice" the data by different types of users 15:47:52 dag nammit! 15:48:02 I added Question 3.2 so we can identify Red Hat employees' responses 15:48:11 #info Section 3 lets us "slice and dice" the data by different types of users 15:48:23 does it feel like a comfortable question? 15:48:32 acozine: how can you distinguish between RH employees and RH AH customers? 15:48:45 felixfontein: that's a problem, true 15:48:55 we're really asking two questions in one 15:49:12 acozine: to whom and by which way this survey will be done ? pop-up on the website randomly ? 15:49:28 well if our focus is community docs, it would lump all the 'non community' people together? 15:49:30 Do you use Ansible at work? and Do you work for Red Hat or for a company with a relationship to Red Hat 15:49:33 Cool, has gwmngilfen been helping you with the survey? 15:49:45 abadger1999: yes, gwmngilfen has been awesome 15:49:52 Excellent :-) 15:50:08 he asked us to include the "how long have you been using Ansible" question 15:50:23 so he can cross-refernce this data with other data he has collected 15:50:55 baptistemm: we will put it on survey monkey and publicize it through social media, the Bullhorn, etc. 15:51:08 Ty [abadger1999](https://matrix.to/#/@freenode_abadger1999:matrix.org) :) 15:51:53 how long of a survey is "too long"? 15:52:22 I think it has a good length. it's not too long, but contains a good amount of questions. 15:52:36 for some people, more than one question is already too long. let's ignore those :) 15:53:11 I considered adding "Is there a question you wish we'd asked you, that we didn't ask you?" but I think we'd get more snark than data from that. 15:54:10 for question 3.2, I really want to make sure community voices are heard, and not drowned out by a high response rate from within RH 15:54:13 We could also add it to the docs banner on latest/devel if we wanted to go that far 15:54:21 (the survey link) 15:54:47 but I'm worried that the question seems like it's motivated the other way - that RH votes or customer votes will "count extra" 15:55:47 * gwmngilfen is just getting tea but will review the current draft in a few mins :) 15:56:28 acozine: I see what you mean, but I don't think it should be a big problem 15:56:34 so the final deadline is one week from today, so we can include a link in the next issue of The Bullhorn 15:56:36 I'd just get greg's advice and go w/ it. He's the data guru 15:56:51 thanks felixfontein samccann 15:57:14 #info feedback deadline is Dec 1 so we can get the survey link into the next Bullhorn 15:57:26 * gwmngilfen blushes 15:57:35 okay, we're half an hour over 15:57:40 #topic open floor 15:58:03 all questions welcome 15:58:11 bring your PRs yearning to get merged 15:58:23 you said, all? 15:58:48 :) 15:58:54 heh, yes, though existential questions will be answered with "42" 15:59:12 heh 15:59:13 I don't have any docs-related PR right now I think (except the collection versions PR for antsibull and I first have to go through abadger1999's feedback) 15:59:36 we're behind on reviewing/merging docs PRs 15:59:40 so there are a lot out there 16:00:03 it's Thanksgiving week in the US . . . Pandemic Thanksgiving 16:00:19 so there's a lot of logistics being debated 16:00:24 I'll put another plug out there for review/feedback on the proposal to split the docsite 16:00:43 samccann: link? 16:00:49 I'll info it 16:00:50 #info please provide feedback by Dec 3 on Separating Ansible 3.0.0 collection docs from ansible-core - https://hackmd.io/TQmzyhCUSSKa22iFR_079A?both 16:00:59 heh, you beat me to it 16:01:04 a link and a deadline. 16:01:18 * samccann feeling accomplished this am 16:01:43 #info No supplementary meeting on Nov. 26, since it's Thanksgiving Day for the US-based docs team 16:01:51 Pandemic Thanksgiving = virtual turkey eating? 16:02:02 felixfontein: https://github.com/ansible-community/antsibull/issues/219 16:02:07 virtual pie eating for my family 16:02:15 since we'll zoom-pie later in the day 16:02:17 felixfontein: my usual group is doing a "drive-through Thanksgiving" 16:02:31 abadger1999: I'll fix that ;) 16:02:40 hee hee :-) 16:02:48 acozine: also sounds interesting 16:02:54 we've done a pot-luck dinner for so many years, everyone makes the same dish year after year 16:02:57 I like this! felix finds a problem, I open a ticket for it, then he fixes it ;-) 16:03:05 hehe 16:03:13 woot! 16:03:18 contributing++ :) 16:03:24 mostly because I already fixed the hard part ;) 16:03:30 so we're packaging them in individual servings, driving by my brother's house to drop them off, then driving by again to pick up one of each dish to take home 16:03:32 :-) 16:03:58 abadger1999: that is some A-grade community manipulation^w management there *chef kiss* 16:05:09 anything else for open floor? 16:06:01 going once 16:06:06 going twice 16:06:18 sold to the little lady w/ the turkey cooking! 16:06:27 * acozine brings down the gavle 16:06:31 er, gavel 16:06:36 NOT ON THE TURKEY!!!! 16:06:47 heh 16:06:51 thanks abadger1999 aminvakil baptistemm dmsimard felixfontein gundalow samccann 16:06:58 to those in the US, Happy Thanksgiving 16:06:58 \o/ 16:07:04 #endmeeting