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