15:32:00 #startmeeting Documentation Working Group 15:32:00 Meeting started Tue Dec 18 15:32:00 2018 UTC. 15:32:00 This meeting is logged and archived in a public location. 15:32:00 The chair is acozine. Information about MeetBot at http://wiki.debian.org/MeetBot. 15:32:00 Useful Commands: #action #agreed #halp #info #idea #link #topic. 15:32:00 The meeting name has been set to 'documentation_working_group' 15:32:35 on my computer/browser, i don't see any lines around the content in the `Return Values` section here: https://docs.ansible.com/ansible/devel/modules/ec2_instance_module.html#return-values 15:32:51 is that just my browser or laptop? or are other folks seeing that as well? 15:32:56 * gundalow waves 15:33:15 acozine: I do see lines 15:33:17 #chairs gundalow samccann dag 15:33:29 #chair gundalow samccann dag 15:33:29 Current chairs: acozine dag gundalow samccann 15:33:30 i see many many boxes 15:33:50 hm, okay, Chrome has lost its furry little mind on my laptop then 15:34:04 felixfontein: rewrote the rendering, and made it more stable, might be related to that ? 15:34:10 it's funny, I see the grid on the parameters, just not on the return values 15:34:29 well, if it only affects me, we don't need to worry too much about it 15:34:30 hmm, I'll look into differences, but might be CSS 15:34:39 hi 15:34:44 welcome jzielke84 ! 15:34:57 are you here for the Docs Working Group meeting? 15:35:13 yes I'd like to discuss my deprecated commands suggestion 15:35:45 excellent - it sounds like we have several more "mechanical" PRs/ideas to review 15:36:17 ("more" in the sense that last week we looked at several PRs of this kind) 15:36:47 ok 15:37:02 anybody else around? Xaroth? felixfontein? shaps? 15:37:10 #chair jzielke84 15:37:10 Current chairs: acozine dag gundalow jzielke84 samccann 15:37:10 I'm around-ish 15:37:17 #chair Xaroth 15:37:17 Current chairs: Xaroth acozine dag gundalow jzielke84 samccann 15:37:19 Hi, yes around-ish too 15:37:26 #chair shaps 15:37:26 Current chairs: Xaroth acozine dag gundalow jzielke84 samccann shaps 15:37:36 awesome 15:37:50 oh, before we get into discussing PRs, a few housekeeping details 15:38:12 NO DaWG (Docs Working Group) meetings the next two weeks 15:38:34 RH is shut down the next two Tuesdays for the holidays 15:38:38 acozine: sorry, I don't have time right now... 15:38:39 Wait, you're getting time off for the holidays? fancy 15:38:40 Why is it called DaWG ? Where is the "a" coming from ? 15:38:59 documentAtion? ;) 15:39:02 dag: it's a bit of a cheat - Documentation 15:39:17 yep, what felixfontein said 15:39:35 or you could see it as 'awareness' or 'awesomeness' 15:39:36 it just makes me smile to be able to say "Hey, DaWGs!" 15:39:43 Slang for "my close acquaintance of an African-American ethnic background" 15:39:45 :) 15:39:46 #info NO DaWG (Docs Working Group) meetings the next two weeks 15:40:04 #info next DaWG meeting January 8th 2019 15:40:28 Xaroth: I like it! Documentation Awesomeness Working Group 15:42:14 okay, jzielke84: is your proposal in PR form? 15:42:58 ehr... so far it's just an issue thread 15:43:23 ah, I see it 15:43:25 https://github.com/ansible/ansible/issues/47844 15:43:36 right 15:44:14 this fits well with our ongoing discussion about the design of the module docs template 15:44:28 ok, great 15:45:03 including https://github.com/ansible/ansible/pull/49966 15:45:21 #topic Mechanical PRs and Issues 15:45:21 #topic module docs template design ideas & changes 15:45:28 #link https://github.com/ansible/ansible/issues/47844 15:45:51 thanks samccann 15:45:59 jzielke84: Hi, thoughts on https://github.com/ansible/ansible/issues/47844#issuecomment-447028661 15:47:44 yeah I read them already. Makes sense to me, if the doc pages are generated by yaml files. We could either probably add a "deprecated" column in the docs niext to the command and before the description or just mark them red based on the deprecated-tag 15:48:12 Both would be better than a "deprecated" info at the end of a long command description 15:48:13 beware that at some point we want to get rid of these deprecated parameters 15:48:35 Would be a bold line at the top of the description, or similar 15:49:18 sure, so if a command int he yaml file has the deprecated-attribute you can decide whether its shown in the docs or not 15:49:42 dag: I was thinking we could validate it agains it into `remove_in_version` from argspec using validate-modules 15:50:12 gundalow: sure, but at this moment the arg_spec PR was not accepted 15:50:18 gundalow: so at this time we cannot do that 15:50:42 ah, from validate-modules, so that's the removal-process 15:50:54 I was thinking of including the information in the module docs from the arg_spec 15:51:35 I'm assuming building docs from argspec is at least n+2 versions away 15:52:39 maybe a deprecated-tag with a date "deprected_since" might also help, since you then can decide to keep depcreated commands within the docs for n-days after they're deprecated so they wont stay in the docs indefinitly 15:53:15 becuse dag was pointing out that at some point the docs need to get rid of them, preventing them to be cluttered 15:53:25 jzielke84: Docs are versioned (in the URL), so a deprecated module option would stay till it's remved 15:53:27 removed* 15:53:48 ok 15:53:51 removal would be triggered by removing the old entry version from something like https://github.com/ansible/ansible/blob/devel/test/sanity/validate-modules/schema.py#L152 15:54:04 upon a new major release, we tend to go over the code and clean up anything that is deprecated 15:54:06 * gundalow is happy to take a look at this and raise a PR 15:54:34 gundalow: you could use the "required" position to state "deprecated" instead 15:54:37 dag: removing one item from the list of `schema.py` would tell us what needs removing. That's how we do the module-level deprecation 15:54:43 looking at felixfontein's comment on the issue - I like the idea of providing the full info on parameter deprecation, the way we do for module deprecation 15:55:24 gundalow: won't always work though, it works for things like this, but not for return value deprecation etc. 15:56:53 Personally, I wouldn't make it too complex. I'd go for deprecated: yes/no (and use the description to add specifics, in bold) 15:57:44 (and the deprecated: yes/no can be replaced with the remove_in_version argspec later) 15:58:18 something like this, maybe make the yes red at least. JUmps in the eye so far and red always has the warning-character 15:59:05 jzielke84: if a parameter is deprecated, we need to make that stand out, yes, but how we do that visually is different from how we indicate it in the yaml docs 15:59:18 the yes/no will not be in the generated docs 15:59:38 ah ok so you're just discussing the data strcture right now 16:00:20 yes 16:00:31 so if deprecated: yes it'll be thrown out of the docs later on automatically right? 16:00:32 visually I would replaced the "required' in this image: https://github.com/ansible/ansible/pull/49966#issuecomment-447788764 16:00:56 ah ok 16:00:57 with "deprecated" maybe even in darkgray/bold 16:00:58 i get it 16:01:20 jzielke84: it will be removed from the docs when we release the version where the deprecated parameter actually gets removed 16:01:21 it cannot be required and deprecated :) 16:01:33 thank goodness for that 16:01:38 schroedingers command ^^ 16:01:44 heh 16:01:52 I guess we can leave this up to gundalow now ;-) 16:02:10 is the meeting over, or does it run for another 30 mins ? 16:02:53 runs another 30 minutes 16:03:04 #action gundalow to create a PR for 16:03:04 Suggestion: Mark deprecated parameters within documentation #47844 16:03:09 #undo 16:03:09 Removing item from minutes: ACTION by gundalow at 16:03:04 : gundalow to create a PR for 16:03:17 #action gundalow to create a PR for `Suggestion: Mark deprecated parameters within documentation #47844` 16:03:28 #topic 16:03:30 acozine: What's next? 16:03:45 Can I propose https://github.com/ansible/ansible/issues/49970 ? 16:03:49 thanks jzielke84 for opening the issue 16:04:00 stick around if you're interested in docs! 16:04:10 dag: sure 16:04:12 You're welcome :-) Well I'm in a hurry a little bit. Writing from the office and nedd to get going in a couple of minutes. So if you don't need any more info I'd request to leave this chat. 16:04:29 join us any Tuesday, same time and place 16:04:36 see you later jzielke84 16:04:49 ok see ya , and thanks for your suggestions 16:04:53 bnye 16:05:09 #link https://github.com/ansible/ansible/issues/49970 16:05:19 I'd like to get rid of the "added in v1.9" bits we have in the module docs if the version is sufficiently old 16:05:35 I don't think it adds any value once we have moved on 16:05:58 agreed, especially for anything from 1.x 16:06:01 some of the (windows) modules have this for almost every parameter (e.g. win_template) 16:06:26 do you have a link handy to a good exmaple? 16:06:31 example 16:06:32 acozine: well, I think it could be moving with the released versions, so we could say we go X versions back 16:06:41 https://docs.ansible.com/ansible/latest/modules/win_template_module.html 16:06:54 for this module it is still relevant though 16:07:14 (the windows modules are relatively new) 16:07:16 there are two bits of metadata there 16:07:24 there's the `version_added` for the module 16:07:41 and then for some of the parameters 16:07:58 correct, both I would cover with the implementation 16:08:42 and since we will have to store what version we will document, we might as well use the same datastore for documenting what docs versions exists 16:09:07 can you walk us through your suggested solution with an example? 16:09:09 I'd propose to use something like in the PR 16:09:17 ``` 16:09:27 oops, too much time on slack 16:09:34 https://github.com/ansible/ansible/issues/49970#issue-391316428 16:09:38 https://www.irccloud.com/pastebin/TnVYmp2G/ 16:10:10 we need this for the website anyway, as we want to more easily move from one version of the docs to another 16:10:13 so this metadata would apply to all docs? 16:10:20 yes 16:11:01 two questions 16:11:03 it would be a metadata file in the devel tree that would be used when generating docs, but possibly also when offering options on the website 16:11:09 how does `devel` fit into this? 16:11:14 and and what does `support_documented` do? 16:11:31 support_documented would be the last version to mention in the docs 16:11:38 ah, okay 16:11:44 so anything older than that (version_compare) would not be mentioned anylonger 16:11:54 so the other metadata would remain in the codebase, we'd just suppress it on publication 16:11:59 yes 16:12:35 removing is an option too, but I don't see the point really :) 16:12:47 * acozine heaves sigh of relief 16:13:05 don't want to ask contributors to remove those bits etc. 16:13:33 coming at this from a 'what I'm used to' perspective...and I'm not used to a 'moving' when supported version, if that's what we're saying 16:13:45 the supported_versions would be useful to add at the top to select your documentation from, devel would always be listed 16:13:48 (aka...i don't have an issue w/ 'supported since 1.9) 16:14:03 and e.g. the latest_version would be useful to identify which version is lates 16:14:29 so at the top there would be the following links: [2.5] [2.6] [2.7 (latest)] [devel] 16:14:52 we could also do: [2.5] [2.6] [2.7 (latest)] [2.8 (devel)] if we wanted to 16:15:04 so this would allow version-to-version navigation for module docs 16:15:05 this could be a drop-down list too 16:15:13 but not for the rst files? 16:15:16 yes, a poor-man's navigation 16:15:19 heh 16:15:33 because of files are moved, we would get a nice 404 message with a search box 16:15:51 samccann: can you say more about what you mean by a "'moving' when supported version"? 16:15:55 even better would be if we had fancy advanced redirects 16:16:24 I'm not sure I'm completely following this all. But let's start with - what's wrong with saying v1.9 is when a module was introduced? 16:16:48 samccann: To whom would that be still relevant 16:16:49 granted we don't support anything that old as a release, but if it's obvious it's still supported, why change? 16:17:04 that information is intended to encourage upgrades, and reduce confusion 16:17:57 at least, that's my understanding 16:18:00 indeed 16:18:53 so if you are running 2.5 (still currently supported) and reading the docs for 2.7 (current latest), you will see fancy new parameters, new modules, etc. 16:19:42 ah so this is to highlight 'what's new' so to speak, not specifically when a module or parameter was added (if it's before the current doc version) 16:19:46 but knowing that a module was added in 1.9 is of purely historical interest, since all currently-supported versions will include that module 16:20:06 correct, that information is no longer relevant 16:20:24 samccann: yeah, and to help someone who tries out a module or parameter that doesn't exist yet in the version they're using 16:20:32 what's even more we only started to collect this information since v1.5 or something, so everything before we already considered "it has always been there" 16:20:35 yeah it's not what I'm used to. In the networking space, if Cisco introduced a command in 10.0, that's what it says, even if the current release is 15.x and 10.0 isn't supported anymore 16:21:32 but maybe I'm just looking at it from the crusty ol-timer perspective and not the moving-faster-than-the-speed-of-light perspective that is our user base for Ansible 16:21:33 samccann: but people are still running 10.0 16:21:52 is that for more than bragging rights or a sense of "this feature is now beyond stable"? 16:22:03 what value does that information add? 16:22:10 dag: but does Cisco still support 10.0? And who's to say people aren't still running Ansible 2.2? 16:22:16 I think at some point we should basically say "this parameter has been here since forever" 16:22:36 that is was introduced in v1.2 or v1.3 has no relevancy, and only adds to the wall of text 16:23:05 samccann: correct, if we expect people to still run v2.2 we should keep it 16:23:18 then it is still relevant 16:23:37 especially if we have older Tower releases shipping v2.2 and definitely if it is supported, or was recently supported 16:23:50 so that's why we have support_documented: X.Y 16:24:08 to me that's the issue. IF people run older versions (supported or not) what are we doing to them here? (and is it 'our problem' so to speak?) 16:24:34 but I would hate to have module docs where every parameter has a "added in vX.Y" where X and Y are all different and very old 16:25:05 yeah I can see what you are saying, by version 5.3, every parameter would have a 'added in' field 16:25:16 we already have that 16:25:30 if we collected this information from the very beginning, every parameter would have this basically 16:25:38 (most original modules were quite basic) 16:25:46 so in a sense we already did this in the past 16:25:58 I think we need more information about what versions customers are using, and whether Ansible is willing to say, "We don't support anything older than 2.5 - upgrade or you're out of luck." 16:26:04 acozine: correct 16:26:22 and I would keep a buffer between what is supported and what we still document 16:26:49 dag: meaning, we document more than what is supported? less? or??? 16:27:16 it might as well be "we don't document the previous major release after 10 minor releases" 16:27:40 acozine: yes, in that case we would do that because not every customer can move to a supported version in time 16:28:00 I don't think we can keep the line at what is supported/unsupported 16:28:12 the current state is "we document and support three released versions plus `devel`" 16:28:18 Everything older than 2.0 would be fine today IMO 16:29:15 acozine: not sure what that has to do with anything :-) We already have "added in v1.0" in our current documentation 16:29:50 heh, I definitely think we should get rid of anything that references 1.x 16:30:19 lib/ansible/modules/utilities/logic/async_status.py:version_added: "0.5" 16:30:25 we have been doing it since ever ! 16:30:55 can't believe that this was added since 0.5, I think this was added later 16:31:14 ah, i sense a historians' feud brewing 16:31:25 well, we're out of time 16:32:19 we are already filtering this 16:32:40 I can see get_url has the force parameter was added in v0.7 16:32:44 but it's not on the docs 16:32:49 so we are already filtering 16:32:59 dag: yes, we use something in Sphinx, apprently 16:33:04 apparently 16:33:35 # Strip old version_added information for options 16:33:35 if 'version_added' in doc['options'][k] and too_old(doc['options'][k]['version_added']): 16:33:35 del doc['options'][k]['version_added'] 16:33:53 so where is `too_old` defined? 16:34:13 TOO_OLD_TO_BE_NOTABLE = 1.3 16:34:18 haha 16:34:23 wow 16:34:41 changing that 1 to a 2 might work better :P 16:34:43 so we can drop my proposal (although I think it would be nice if we had the metadata) 16:34:58 okay, as a first step, let's update that to 2.0 16:35:12 1.9 16:35:20 or 2.0 ? let me check 16:35:25 2.0 :-) 16:35:29 ok, I will make a PR 16:35:33 excellent, thanks 16:35:54 # if a module is added in a version of Ansible older than this, don't print the version added information 16:35:54 # in the module documentation because everyone is assumed to be running something newer than this already. 16:36:11 samccann: you and I can talk to marketing/support/business folks to see whether we want to push that `too_old` version further 16:36:13 #action dag to create PR to make TOO_OLD_TO_BE_NOTABLE = 2.0 (or similar value) 16:36:23 k 16:37:13 dag: we might use your proposal for the version-switching, but that won't happen until the new year 16:37:20 right, we're 7 minutes over time 16:37:26 thanks everybody 16:37:35 happy holidays and all the best for 2019! 16:38:05 acozine: I noticed Google is now indexing latest a lot better 16:38:13 often (not always) the first hot 16:38:14 hit 16:39:00 yes, that's thanks to a change from . . . erg, he isn't here, and his nickname is complicated 16:39:14 https://github.com/ansible/ansible/pull/50097 16:39:21 oh, let me log into Adobe web analytics and check thta 16:39:32 acozine: if you have that PR number, I'm interested to learn how this was done 16:39:37 oh, no wait, it was a PR from Xaroth 16:39:45 ok 16:39:57 anyway, it's awesome 16:40:02 thanks Xaroth! 16:40:06 :) 16:40:14 Must. End. Meeting. 16:40:29 We can go on chatting, but I don't want the transcript to be War and Peace. 16:40:37 #endmeeting