15:31:07 #startmeeting Documentation Working Group 15:31:07 Meeting started Tue Mar 5 15:31:07 2019 UTC. 15:31:07 This meeting is logged and archived in a public location. 15:31:07 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:31:07 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:31:07 The meeting name has been set to 'documentation_working_group' 15:31:18 #chair alongchamps felixfontein 15:31:18 Current chairs: acozine alongchamps felixfontein 15:31:23 who else is around? 15:31:55 dag orthanc decentral1se Pilou ? 15:32:07 I know samccann is away from her desk 15:32:38 o/ 15:32:49 #chair dag 15:32:49 Current chairs: acozine alongchamps dag felixfontein 15:32:57 Xaroth: you around? 15:33:08 sorta 15:33:44 Xaroth: okay, I'll ping you by name if we need input on the CSS thing 15:33:53 * Xaroth nods 15:34:07 okay, we've got two items on the agenda 15:34:21 #topic duelling Sphinx themes 15:34:58 * samccann strolls in late 15:35:01 details of the problem we're trying to solve: https://github.com/ansible/ansible/issues/53071 15:35:32 PR that solves part if not all of the problem: https://github.com/ansible/ansible/pull/49289 15:35:38 samccann: welcome! 15:35:45 #chair samccann 15:35:45 Current chairs: acozine alongchamps dag felixfontein samccann 15:36:17 looks like gundalow built a local test of the PR branch 15:36:30 anybody else look at this since last week? 15:37:10 or have comments/insights/questions/concerns? 15:37:16 i looked at it as well. Paged few a few different places and it seems all okay to me. (was more a spot check of random pages vs page by page clicking) 15:38:01 samccann: that's great - I think anything glaringly wrong with the theme should show up on most pages, so spot-checking should give us decent coverage 15:39:30 I see a few PRs that made changes to the theme we're deleting 15:39:54 for example, dag, you put in https://github.com/ansible/ansible/commit/49afb3da3472115aa671fe47a779e80076dad3b7#diff-7779bd267e3df64f56d52b96ee651395 15:40:22 ah, looks like that one changed both themes? 15:40:38 yeah I was wondering if we can merge this PR, and then dig back into what changed on it in the past year, and make sure it's in the current theme? 15:41:23 looks like this one changed both as well: https://github.com/ansible/ansible/commit/fa5c0282a4816c4dd48e80b983ffc1e14506a1f5#diff-7779bd267e3df64f56d52b96ee651395 15:41:23 also for that dag PR you linked to - didn't it change both themes? 15:41:37 * samccann must read the full thread 15:41:57 samccann: I'm hoping we can dig into it right now 15:42:06 ah ok 15:42:11 yeah, I changed all occurrences, that was the safest ;-) 15:42:16 it's only a year's worth of changes, since the new sphinx_rtd_theme was introduced in early 2018 15:42:22 don't expect me to know how it was designed 15:43:15 hm . . . what about this one? 15:43:16 https://github.com/ansible/ansible/commit/9c81b5d92b9aa57b23410620cb0b43c7fe6aa81e#diff-7779bd267e3df64f56d52b96ee651395 15:43:40 here's the PR for that one: https://github.com/ansible/ansible/pull/36728 15:43:44 it only changed the old theme 15:44:07 samccann: did you look at the module docs when you built from Xaroth's PR? 15:44:25 TBH if someone only changed the old theme, and did not notice the website didn't have his changes, it's most likely not important... 15:44:30 I believe I did, but I can regenerate and take another look 15:44:35 not sure if we should spend time on that if the original submitter didn't either 15:46:06 dag: fair enough . . . I just want to be sure we're not unwittingly re-introducing a problem we've forgotten about 15:47:07 I remember around the time of the new theme, we had a bunch of issues that we thought we had fixed, and we didn't always follow up on whether the fix made it to the published version 15:47:39 anyway, that's the last one 15:48:04 because the new theme came in with Scott's big refactoring in https://github.com/ansible/ansible/pull/36067 15:48:41 i'll dig into that PR for the doc table fix... I see the change is not in the current theme so want to see if the original problem still shows up 15:48:44 acozine: if this is in the old theme, we wouldn't be re-introducing it, or am I not understanding this correctly ? 15:49:26 dag - for me, it's a case of someone saw something and fixed the wrong theme. I want to be sure what they originally saw isn't lingering in the current theme 15:49:37 dag: I'm remembering something that we fixed in the old theme, and then wondered why the fix never got published 15:50:48 ok, but should we be doing this in the meeting ? :-) 15:50:58 dag: this is the one https://github.com/ansible/ansible/pull/45089 15:51:05 anyway, I think we've covered it 15:51:23 #actionitem merge Xaroth's remove-duplicate-theme PR 15:51:40 acozine: that issue is not fixed, the same problem exists one level deeper :-( 15:52:11 someone with a web design background should be going over the site IMO 15:52:13 #actionitem double-check grid on module docs in the "big three" browsers after publicaton 15:52:20 dag: oh, I agree 15:52:30 do you have anyone to recommend? 15:52:40 no, you asked me once already ;-) 15:53:13 heh, well, it's an ongoing concern 15:53:17 our index-page is also very boring: https://docs.ansible.com/ansible/latest/index.html 15:53:37 no graphs, no image, just a lot of text 15:53:59 Red Hat could be doing better ;-) 15:54:19 agreed 15:54:34 need uptick graph with 'we are bestest' 15:54:34 though I'm prioritizing "broken" over "boring" 15:54:41 #chair bcoca 15:54:41 Current chairs: acozine alongchamps bcoca dag felixfontein samccann 15:54:44 I have seen flyers and other marketing material enticing potential customers :-) 15:55:01 dag: do you want marketing in charge of docs? 15:55:11 sadly the people who design those do not work in the technical documentation area 15:55:16 bcoca: The competition is miles behind us :-) 15:55:35 bcoca: well, I would let them give input just to make things more attractive 15:55:39 i dont dispute that .. but there are doors i prefer remained locked 15:55:45 the ultimate goal is to have good-looking, accurate, maintained docs 15:55:52 dag: you dont interact with marketing often do you? 15:55:53 but for now I'll settle for accurate and maintained 15:55:56 I don't want them to rewrite the docs :-) 15:56:10 acozine++ ^ 10k 15:56:28 * gundalow waves 15:56:34 #chair gundalow 15:56:34 Current chairs: acozine alongchamps bcoca dag felixfontein gundalow samccann 15:56:35 (was in another meeting) 15:56:42 I am sure the marketing material that Red Hat puts out is accurate and maintained too 15:56:53 I got some survey proof that our ansible docs are rockin it... so yeah, the doc content for sure is doing well. But a bit of website fun would be nice 15:56:55 in all fairness, our marketing team has not been invasive since i've been here, i just had really bad experiences else where . .. truth/accuracy goes out the door 15:57:26 for https://docs.ansible.com/ansible/latest/index.html like with scenario guides, we could reduce toc-depth 15:57:45 gundalow yeah that's on the todo list (the short todo list) 15:57:53 short-term that is... yeesh 15:57:58 woot 15:58:52 scenario guides could have 'cloud logo' adjacent to them 15:58:56 next agenda item is about documenting singular/plural parameters 15:59:00 though that might be a copyright issue 15:59:10 #topic documenting singular/plural parameters 15:59:13 If we reduce toc-depth, the menu becomes even less useful, and with breadcrumbs it does not improve user's finding where they are in the docs 15:59:13 perhaps in lieu of significant website changes, we can make incremental fixes like the scenario guide toc fix 15:59:30 many years ago the documentation was readable from beginning to end, like a book 15:59:45 and it would become progressively more complex build on the stuff you learned before 15:59:48 many years ago docs were 10 pages 15:59:57 bcoca: correct :) 16:00:05 but i agree, its nice to have a gentle slope 16:00:21 bcoca: but now you could read a few pages, and have no clue if you read 50% or 20% or 1% 16:00:22 now we have more than 10pages on 'module categories' 16:00:33 dag: yes, more beginner-friendly docs, more build-on-what-you-know docs are on the roadmap 16:00:37 becuase you jump from one part to another, no clue what you skipped 16:00:46 dag: I was refering to /index.html only, not the left nav bar 16:00:48 'begginer's guide to the ansible universe' 16:01:05 gundalow: ah, the in-page index, sorry 16:01:33 gundalow: the index is not my problem actually, I don't mind more details in there, I mind the boring introduction text 16:01:34 'first there was the prompt .. then the remote prompt (rlogin) .. which we had to make secure (ssh) ... then we had parallel ssh + shell ... the horror! .. ansible comes to save us all! 16:01:39 nobody reads that these days 16:01:41 gundalow: sorry, I was thinking the left-hand nav as well... 16:01:55 we can start a proposal for a Beginner's Guide, with a suggested TOC 16:02:25 I'd welcome feedback on a good path for teaching What You Need to Know About Ansible 16:02:31 however, we digress . . . 16:02:31 #undo 16:02:31 Removing item from minutes: 16:02:40 dag: did you want to talk about https://github.com/ansible/ansible/pull/53062#discussion_r262074264? 16:02:43 bah, that didn't do what I wanted it to :( 16:02:51 (it is your agenda item . . . ) 16:03:51 looks like zodbot has a bug 16:04:18 why should it be different from the rest of us? 16:04:47 I never give up hoping to meet something/someone without bugs ;) 16:04:50 acozine: I don't know if there is consensus about this, and whether we need to document it 16:05:20 acozine: but this has been done before in other modules apparently, so making sure reviewers know that adding aliases (especially in new modules) should be frowned upon 16:05:45 is adding aliases to be frowned upon an official ansible policy? 16:05:51 I can see only one cases where this might be useful (for consistency/abstraction cfr. other modules) 16:05:51 hum, confused, what's the question? 16:06:15 the original question revolved around whether `ssh_key` should be an alias for `ssh_keys` 16:06:50 for convenience (because ssh_keys could hold a single key) 16:06:52 some argue that offering both makes things simple, others argue that parameters that allow multiple values should always be expressed as plurals 16:07:17 and some (like me) would like to avoid aliases whenever possible anyway ;) 16:07:42 having one thing with 2 names is always more confusing IMO 16:08:08 I agree, and I also agree that if someone sees a sample playbook with `ssh_key` they might not realize that they can provide more than one 16:08:17 my nickel - the orrigina question of singular vs plural - I agree w/ dag - keep it plural. If we want to show flexibility, put an example of one key and and example of multiple keys in the example session 16:09:06 felixfontein: I agree, and we need to work on an alias-deprecation mechanism, just like we need a return-value deprecation mechanism ;-) 16:09:07 dag: in acme_certificate, there's an option called "csr" (for certificate signing request), with an alias "src" (for source). the examples feature both aliases. I think I've seen two PRs where people thought one of them was a typo and wanted to "fix" the examples. 16:09:08 yep - because making a predictable, unified user interface is the best documentation possible 16:09:22 I am also inclined to agree that adding an alias in a new module should require some significant 'special circumstances' 16:09:26 dag: a good mechanism for deprecating aliases would be really nice! 16:09:45 (aka allowed but frowned upon unless there is strong reason) 16:10:36 so the narrow question for the docs group is: do we document something about "aliases are frowned upon" or "keep your user interface simple, don't use aliases except for backwards compatibility" 16:10:44 samcann: we allowed it for consistency between sets of modules (i.e. abstraction) and we allowed it for backward compatibility (which requires a deprecation mechanism) 16:10:54 samcann: should we document it like that ? 16:11:06 * acozine looks for the page where this should go 16:11:10 acozine: I like that addition 16:11:20 "refrain from adding aliases, especially in new modules, naming is important so pick good names from the very start" 16:11:28 same here, consistency between modules is a good thing 16:11:46 maybe here: https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html#designing-module-interfaces ? 16:12:05 You can put that on my name, I'll do the necessary 16:12:10 side q: do we have guidelines for common parameter names? e.g. username vs vcenter_username, and similar 16:12:50 alongchamps: we should probably revision some of the current practices :-/ 16:13:33 but since it may mean a lot of changes across the modules, we probably need a deprecation mechanism before attempting any such work 16:13:54 agreed 16:14:21 is there any way a username for foo module could be confused with a username for bar module? It's a logical hierarchy when I'm looking at a playbook, so I'd be inclined to say no need for vcenter_username unless that is the identical name to what is in the vCenter cli/gui itself 16:14:22 dag: sounds like the fix you have in mind involves a lot more than docs 16:14:27 alongchamps: nop, though it's something I've said we should do (like `verify_certs` (or whateverits called)) 16:14:58 samccann: that's what we thought, but then a vcenter-module requires a username for something else, and you happen to already have a username parameter 16:15:19 the vCenter stuff is usually just one set of credentials for a given module, at least in my experience 16:15:27 dag: yes, the exception is of course if the module has two very similar parameters - something has to change 16:15:31 samccann: which overcomplicates things, my new opinion is that everything connection-related should be name-spaced 16:15:31 and it's for whatever endpoint you're going to, which could be a vCenter or an single ESXi host 16:15:58 dag: hmm. not sure you've convinced me of that name-space need. 16:16:00 especially since I can see connection-related parameters to move to a connection-plugin (and the inventory) over time anyway, even for VMware 16:16:23 * alongchamps wonders what a connection-plugin is 16:16:34 alongchamps: the module to create vcenter users probably has 2 username parameters :) 16:16:49 huh, we have an entry in the docs for env var naming: "Use module-specific environment variables. For example, if you use the helpers in module_utils.api for basic authentication with module_utils.urls.fetch_url() and you fall back on environment variables for default values, use a module-specific environment variable like API__USERNAME to avoid conflict between modules." 16:16:57 that's a good point, dag 16:16:58 dag: do you have a pointer to this module so we can see what it looks like? 16:17:17 cuz if vcenter has two usernames, then they must mean different things, right? 16:17:25 https://www.irccloud.com/pastebin/ntUkGhwz/ 16:17:25 https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/cloud/vmware/vmware_local_user_manager.py 16:17:28 is a good example 16:17:29 or be a list of usernames to add to vcenter? 16:17:46 * samccann reading the links 16:17:48 alongchamps: currently every vcenter module has the same set of connection parameters, if we had a vmware connection plugin (like i.e. ssh) the modules don't need the connection information and the connection is made by Ansible, not y the module 16:17:50 in that case you have username/password for the connection and local_user_name/local_user_password 16:18:05 dag: I like it 16:18:27 for now though, ctrl+c, ctrl+v is my friend when writing playbooks 16:19:37 isn't there this default module option thing which you can use to drastically reduce ctrl+c/ctrl+v (at least in some cases)? 16:20:10 alongchamps: here is my example for ACI: https://github.com/ansible/ansible/issues/36100 16:20:17 alongchamps: my nickel would have been to give the vCenter username a name like vcenter_username (as you stated earlier) now that you show this example 16:20:53 some modules can go to a single ESXi host though, such as the one to manage host virtual switches 16:21:04 but that is a specific case. I'm still not convinced every username (for example) has to be foo_username in a module. I think it only becomes an issue when you have two parameters that can be mistaken for one another 16:21:32 agreed, I think this is a matter of having strong enough guidelines for what to use for the most common fields 16:23:02 so . . . back to the original topic 16:23:14 now that I half a clue what a connection plugin is (thanks dag!) maybe that's a guideline to add? - if you have a bunch of related modules that all have the same connection parameters - create a plugin instead 16:23:30 sorry acozine :-O 16:23:38 samccann: ;) 16:23:40 +1 samccann 16:23:44 samcann: it's not that simple, but it could help in making some of it go away 16:24:01 so I'll add some notes about aliases and parameter naming to the documentation for reviewers and contributors 16:24:06 next topic ? :) 16:24:29 #actionitem dag to open a PR with guidelines for naming to the dev guide 16:24:40 hm, apparently that's not the right command 16:24:44 i think for the original topic, we were in agreement w/ dag's comments in that PR? So the action would be that we pop in and add that comment to show we agree? 16:24:51 +1 from me 16:24:59 #action dag to open a PR with guidelines for naming to the dev guide 16:25:04 gundalow: thanks 16:25:14 Another small topic is this PR: https://github.com/ansible/ansible/pull/53332 16:25:14 ok gonna add that comment now 16:25:15 #topic open floor 16:25:25 samccann: thanks 16:25:31 we've got five minutes left 16:25:34 we need to restore the original ISSUE_TEMPLATE.md that was removed a month ago 16:25:46 it was there for a reason 16:26:04 dag: any recollection why it was removed? 16:26:13 (i.e. I removed it once before, but webknjaz luckiy corrected my PR .-)) 16:26:23 because it was believed to be unneeded 16:26:32 ah, that's too bad 16:26:46 d'oh! 16:26:54 I thought we had moved to individual templates for specific issue types 16:27:03 and the PR was merged before I saw i this time 16:27:09 yeah that sounded familar to me acozine 16:27:14 acozine: sure, but not all interfaces do that currently 16:27:27 take your mobile phone, go to ansible/ansible and open aan issue 16:27:29 not all GitHub interfaces? 16:27:37 gotcha 16:27:38 #info Any changes to ISSUE_TEMPLATES or PR_TEMPLATES need real review via jctanner to check for Bot impact 16:27:50 yeah, this is github issue, they have not updated all their 'client code' to deal with it 16:28:08 gundalow maybe you can ask Github to fix that next week ;-) 16:28:09 so on Mobile if I got to github.com/ansible/ansible/issue/new I see `Please raise issues via the [new interface]....` text 16:28:13 not sure if this was on your list 16:28:15 well, meanwhile we need a workaround 16:28:39 so the only reason we had this (more generic) issue template was for this use-case :-/ 16:28:43 dag: I believe you, and thanks for noticing the problem 16:29:06 dag: how are you opening an issue from ansible/ansible/issues 16:29:21 though .. im curious .. who uses phone to open issue? ... hard to paste playbook and error output 16:29:36 ... unless you are running playbooks from phone? 16:29:49 likely also hard to actually fill out a template from a phone 16:30:14 okay, so the PR in question was https://github.com/ansible/ansible/pull/51657 16:30:53 If that template is only used by mobile view on website I'm -1 16:31:09 does "mobile view" include tablets? 16:31:12 or just phones? 16:31:22 probably both 16:31:27 but resizable profiles 16:31:27 yeah was thinking that - tablets frequntly use the mobile view as well 16:31:53 even if for tablets I'm -1, people need to be using https://github.com/ansible/ansible/issues/new/choose 16:31:53 my table shows the desktop version 16:31:55 * bcoca tries site on moto flip phone ... slooooow 16:32:09 smart table? 16:32:14 or lost a t? 16:32:18 tablet :) 16:32:36 no option to even view mobile version 16:32:42 the only tablet I have is actually made of clay 16:32:49 nexus shows full version, but nook shows mobile 16:33:08 so what is the argument against having a generic template? 16:33:12 maintenance? 16:33:29 does it interfere with the bot? 16:33:31 gundalow: "People need to be using..." we can't force people, only Github can 16:33:32 acozine: you in charge of maintaing persian 5k old docs? 16:33:34 * alongchamps lunchtime 16:33:48 gundalow: so if there's no template, chances are they open an issue without template 16:33:49 alongchamps: bye, thanks for participating! 16:33:54 acozine: We've put various bits of time and effort into the dedicated templates https://github.com/ansible/ansible/issues/new/choose 16:34:12 so if the fix is I ask GitHub to ensure that for https://github.com/ansible/ansible/issues/new on mobile directs to https://github.com/ansible/ansible/issues/new/choose then I can do that 16:34:19 gundalow: they cannot click on the link, because it's inside the editor, and copy&pasting a URL is not convenient either 16:34:21 so trying to create an issue on my iphone I get something that tells me to please rais issues via the [new interface] and points me to github 16:34:43 if they can't copy paste then how are they going to fill in the template 16:35:03 gundalow: I spend time and effort on the generic issue template too, after we split them out 16:35:19 you can report basic issues fine on a mobile phone 16:35:21 and I have 16:35:27 gundalow: fwiw the new interface isn't mobile friendly 16:35:35 I do reviews on my mobile phone too 16:35:40 (aka the open issue button scrolls off horizontaly 16:35:55 I dunno how often anyone does this... just pointing out what I'm seeing right now 16:35:58 what do we win by removing it ? 16:36:09 I don't understand 16:36:24 idk, i would check pr that removed and ask 16:36:29 what happened to Contributor Experience ? :-) 16:36:40 dag: I'm just trying to understand the use-case 16:36:44 PR was #51657 16:36:49 before we put in duplicated files 16:37:01 if anything, Github should get rid of this, if not we can't make people not use mobile phones 16:37:11 we already had duplicated files 16:37:29 https://github.com/ansible/ansible/issues/new on laptop doesn't give link to https://github.com/ansible/ansible/issues/new/choose 16:37:29 maybe we shouldn't have merged for removal when we did 16:37:41 So maybe it should on desktop & laptop view 16:37:59 dag: if mobile: https://github.com/ansible/ansible/issues/new had a link to https://github.com/ansible/ansible/issues/new/choose would that make you happy? 16:38:29 gundalow: if Github no longer uses the old template for anything, that would make me happy 16:38:31 dag: gundalow: let's try talking to GitHub, since that would be the ideal solution 16:38:32 gundalow: I think it does already 16:38:51 but as long as there are cases where people would end up on the old template, we should offer a proper template 16:38:58 #action Will make issue templates a GitHub problem 16:39:00 if they could redirect mobile traffic to the "select an issue" option 16:39:05 Let me speak to them and see what they say 16:39:07 so i can open an issue on my phone, and that gives me a link that I cut n paste that gets me to the new form. Usable.. not perfect, but usable 16:39:07 What's next? 16:39:17 we're already over time 16:39:24 ok 16:39:29 Thanks everybody! 16:39:45 thanks folks 16:39:51 chat with you soon! 16:39:58 samcann: before you would simply get the template 16:40:10 add agenda items for next week to the issue and/or post them here 16:40:37 #endmeeting