15:31:32 <gundalow> #startmeeting Ansible Documentation Working Group
15:31:32 <zodbot> Meeting started Tue Dec 11 15:31:32 2018 UTC.
15:31:32 <zodbot> This meeting is logged and archived in a public location.
15:31:32 <zodbot> The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot.
15:31:32 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
15:31:32 <zodbot> The meeting name has been set to 'ansible_documentation_working_group'
15:31:38 <gundalow> #chair acozine samccann
15:31:38 <zodbot> Current chairs: acozine gundalow samccann
15:31:59 <acozine> hello, time-zone-appropriate greetings to all!
15:32:03 <acozine> who's around?
15:32:48 * acozine could hear a pin drop
15:33:20 <felixfontein> I'm here
15:33:25 * samccann drops pin
15:34:08 <acozine> #chair felixfontein
15:34:08 <zodbot> Current chairs: acozine felixfontein gundalow samccann
15:34:15 <acozine> samccann: I heard that!
15:35:36 <acozine> I'd like to look at another "mechanical" PR (that is to say, a PR focused on process rather than on words)
15:36:18 <gundalow> Sounds good, what's on the list?
15:36:46 <acozine> https://github.com/ansible/ansible/pull/45949
15:37:24 <samccann> #topic Mechanical PR
15:37:28 <samccann> #link https://github.com/ansible/ansible/pull/45949
15:37:32 <acozine> this PR would highlight links in the module docs by giving them a special section
15:40:07 <acozine> I have a lingering concern that having two different ways to format links (with `M(module)` or `L(link)` in most of the module doc, and with `- module` or `- name` in the See Also section may cause Future Me confusion
15:40:28 <acozine> otherwise, I think it's a good idea
15:41:04 <acozine> if we train users to look for related materials in a single section, over time that will help everyone find the documentation they need
15:41:48 <gundalow> +1 to merge `seealso`
15:42:00 <samccann> I like the see also, but you're point about the different ways to do links is also valid.  Can we add something to the description to point out specifically that the links are different?
15:42:20 <gundalow> samccann: description of?
15:42:27 <samccann> I know it's in the example, but a sentence to say use `-module` instead of `C(Module)` in this section would help
15:42:51 <samccann> somewhere around here - https://github.com/ansible/ansible/pull/45949/files#diff-c0ea479c6bd02ae5e1979ea7089c739fR233
15:43:08 <acozine> We can add a section to https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html#linking-within-module-documentation
15:43:34 <felixfontein> sometimes it is useful to link to something "inline" (i.e. outside the seealso section), I guess using both the right way is not that simple. though also not too hard.
15:44:25 <acozine> I agree that we should keep both options for adding links to the module docs
15:45:21 <acozine> since some links are specific to a certain parameter, where others are related to the entire module
15:45:39 <gundalow> Need both ways, they solve different problems
15:46:04 <felixfontein> yes, and sometimes you want to link to a specific subsection of some document (which would be linked 'globally' in seealso) in the options description
15:46:06 <samccann> yep, agreed
15:46:27 <gundalow> Can we merge, then if there are specific things we can always tweak `docs/docsite/rst/dev_guide/developing_modules_documenting.rst` in a follow up PR
15:46:37 <samccann> +1
15:47:08 <acozine> I'm okay with that approach
15:47:13 <acozine> felixfontein: what's your vote?
15:49:30 <felixfontein> +1
15:49:53 <samccann> #agreed - merge `seealso` pr
15:50:00 <acozine> okay, I'll kick CI off and merge when it's green
15:50:11 <samccann> \o/
15:50:44 <samccann> #action acozine to kick CI off and merge when it passes
15:52:01 <acozine> here's another "mechanical" one: https://github.com/ansible/ansible/pull/42888
15:52:35 <samccann> #topic webdocs: Differentiate between type and required #42888
15:52:45 <samccann> #link https://github.com/ansible/ansible/pull/42888
15:53:08 * gundalow kicks CI as it's `stale_ci`
15:53:24 <acozine> We are talking with an internal team that specializes in HTML/CSS specifically for documentation
15:53:43 <acozine> They may have some time to help us with the main docs landing page (docs.ansible.com)
15:54:17 <acozine> and while we have their attention, I can ask them for ideas about marking required parameters
15:54:58 <felixfontein> sounds like a good idea!
15:55:20 <felixfontein> the current situation is pretty ugly, but having ** instead of 'required' doesn't sound very appealing, either
15:55:20 <acozine> this PR has a lot of different ideas in it, so it seems like a good starting point
15:55:42 <felixfontein> yes
15:55:50 <acozine> I agree that the current situation isn't good
15:55:56 <samccann> personally I like the 'required' word there. helps me scan the list to know what I have to fill in vs optional
15:56:09 <felixfontein> putting required into the second column is only a good idea when it's empty, otherwise it needs much more vertical space than the first column
15:56:29 <felixfontein> maybe types should have a different color than required? that would make required easier to spot
15:57:14 <samccann> I was thinking something similar - instead of read, put the type in italics
15:57:21 <samccann> red even
15:57:35 <acozine> relying on color or typeface isn't screenreader-friendly
15:57:56 <acozine> at least, relying on color or typeface alone isn't
15:57:56 <felixfontein> maybe we should have a small "type" icon on the left of it :)
15:58:04 <samccann> but the screen reader would still say bool required right?
15:58:12 <felixfontein> (with an alt-tag "type:", then it's screenreader-friendly)
15:59:24 <acozine> felixfontein: when you say "small 'type' icon", what do you mean/
15:59:26 <acozine> ?
15:59:29 <felixfontein> isn't it possible to add "invisible" things which are still read by screenreaders? (except using alt-tags for <img>)
15:59:44 <felixfontein> acozine: that's a very good question :) I have no idea what kind of icon would be nice there
16:00:17 <acozine> I think if we use styles we can add tags to the style markers that screenreaders can pick up
16:00:31 <acozine> I will have to do more research though
16:00:54 <felixfontein> you mean, like '::before { content: "Type: " }' with visibility restricted to screen readers?
16:01:19 <felixfontein> using styles would be a good idea anyway, having all CSS inline is pretty ugly
16:03:29 <acozine> I'm not sure what it looks like in the HTML - my limited understanding is that you can define a style called `Required` that turns text, for example, bold, red, and italic (overkill, I know, but for the sake of example) . . . and then wherever that style is used in a document, add a screenreader tag of "Required field"
16:03:31 <acozine> or something
16:04:11 <felixfontein> yes, depending on what you mean by adding a screenreader tag, that works
16:04:20 <acozine> another approach might be a small column to the left, just wide enough for an asterisk, and put an asterisk in it when a field is required
16:05:10 <felixfontein> would it be that much different from the trailing ** dag suggested?
16:05:33 <felixfontein> it's definitely easier to see, though, since it is its own column
16:05:36 <acozine> to my eye it's easier to scan a standalone column
16:06:01 <acozine> exactly, easier to see than trailing **, which varies its placement depending on the length of the field name
16:07:51 <acozine> though then we would miss the fun of finding icons for "boolean" (light switch?) and "integer" and so on ;)
16:07:59 <felixfontein> lol
16:08:14 <felixfontein> no, I meant a generic icon for type, followed by the type name :)
16:08:20 <acozine> oh, heh
16:08:24 <felixfontein> [icon] bool
16:08:42 <felixfontein> so that if the alt-tag of [icon] is "Type:", it will be read as "Type: bool" by a screenreader
16:08:52 <acozine> much more sensible, though not as much leeway for creativity
16:09:02 <felixfontein> finding icons for types would be fun, too, but would make the documentation much harder to read :)
16:09:06 <felixfontein> hehe yes
16:09:10 <gundalow> Seems to be getting a bit complex
16:09:32 <acozine> why don't I add this to my list of "ask the CSS guru team" items
16:09:42 <gundalow> +1
16:09:43 <acozine> I can report back next week
16:09:52 <samccann> +1
16:09:57 <acozine> I think we're meeting on Wednesday (for the first round)
16:10:06 <felixfontein> might also be a good question for some UX experts
16:11:05 <acozine> yes . . . I'm hoping this team has all that expertise
16:11:49 <acozine> okay, dag has one more open "mechanical" PR : https://github.com/ansible/ansible/pull/46541
16:12:01 <acozine> I have not looked at this one in detail
16:12:04 <samccann> #action acozine to discuss options with CSS team on how best to display both type and required status in module parameter tables
16:12:45 <samccann> #topic - Improve the output when processing docs PR 46541
16:12:53 <samccann> #link https://github.com/ansible/ansible/pull/46541
16:13:03 <acozine> ah, correction, I have not looked at this one in detail in several weeks
16:13:45 <felixfontein> I just wanted to write something with months, but it isn't even two months ago :)
16:14:55 <acozine> I hope that means we are keeping up with the incoming PRs a bit better
16:15:05 <samccann> :-)
16:15:12 <acozine> when a PR less than two months old seems much older
16:15:23 <felixfontein> I would really like the try/except with print in except and re-raise, so that when errors happen, the module name is printed before the error
16:15:43 <samccann> on this one, I'd worry that new contributors (who may pick doc fixes as something to get their feet wet) will not realize things are churning under the covers if that message stays there for a long time
16:16:06 <acozine> agreed on both points
16:16:59 <acozine> felixfontein: would you be willing to pull the branch and try adding the try/except to it?
16:17:47 <felixfontein> it would be nice if it could display some "processing" symbol (like cycling through -/|\), but I'm not sure how hard this will be; but then people would notice that something is happening. no idea how that will interoperate with CI, though.
16:18:09 <acozine> ah, good point
16:18:29 <samccann> even a message above it to say'this may take some time' would help
16:19:39 <acozine> at my last job when we ran import processes (for digital library collections) we issued a standard warning: "this is slow"
16:19:56 <acozine> I always wanted an ASCII-art image of a sloth
16:20:13 <felixfontein> I added an example for the try/except here: https://github.com/ansible/ansible/pull/46541/files#r240681075
16:20:40 <gundalow> (back)
16:20:52 <acozine> I don't think Shippable cares about the console output if it doesn't include an error, but we could test it to be sure
16:21:01 <acozine> felixfontein: that was fast!
16:21:11 <samccann> #info would help if there was some indication that the build is still running and not stuck
16:22:24 <samccann> #info felixfontein provided suggestion to include try/except so that the output correctly shows which file the build fails on
16:22:30 <gundalow> By the time we print out `Evaluating module files` do we know how many files, could we add that with a `this may take an hour for a full build`, or somesuch message?
16:23:47 <acozine> gundalow: won't the overall build time depend on the speed of the machine doing the processing?
16:24:05 <acozine> when I upgraded my laptop, the build speed dropped a lot
16:24:13 <acozine> sorry, I mean the build time dropped by a lot
16:24:17 <acozine> it got faster
16:24:38 * acozine mumbles something about English being her first language, really
16:25:45 <felixfontein> :)
16:25:48 <acozine> but if we know the number of files, we could post something like `processing N module files - this could be slow, may we suggest a cup of coffee?`
16:26:56 <acozine> felixfontein: any ideas about printing out some feedback or warnings for the user here?
16:27:08 <felixfontein> dag seems to be around (he just merged my suggestion)
16:27:12 <gundalow> acozine: yup, that would be fine
16:27:39 <acozine> hey dag, welcome
16:27:58 <dag> o/
16:28:09 <felixfontein> dag: here :)
16:28:13 <acozine> #chairs dag
16:28:23 <gundalow> -s
16:28:26 <dag> the only Ansible channel I wasn't auto-joining...
16:28:30 <acozine> #chair dag
16:28:30 <zodbot> Current chairs: acozine dag felixfontein gundalow samccann
16:28:35 <acozine> gundalow: thanks
16:28:37 <felixfontein> dag: something you should change ;)
16:29:09 <acozine> we're just finishing up the docs working group meeting
16:29:24 <dag> :-)
16:30:36 <acozine> and looking at https://github.com/ansible/ansible/pull/46541, and thinking that a message to users that the build is slow would reassure them that something is happening when they run `make webdocs`
16:31:08 <felixfontein> I changed the first line of process_plugins as follows:
16:31:11 <felixfontein> for module_index, module in enumerate(module_map):
16:31:11 <felixfontein> sys.stdout.write('%s\r' % ("-/|\\"[module_index % 4]))
16:31:11 <felixfontein> sys.stdout.flush()
16:31:27 <felixfontein> now one can see that it does something :)
16:32:01 <acozine> for those of us whose first language isn't Python . . . what will that print out?
16:33:59 * samccann brb
16:34:00 <felixfontein> the first character of the current line will change between '-', '/', '|', '\', and back to '-', etc., until something is printed (like 'rendering: ...')
16:34:14 <felixfontein> so you can see that something is going on (it will change after each file processed)
16:34:47 <felixfontein> I'm not sure whether that's really needed, though, since this part of the docs build process is very fast
16:35:01 <acozine> oh, so it does an ASCII spinning thing . . . that seems like a good solution
16:35:05 <acozine> which part is fast?
16:35:47 <felixfontein> creating the .rst files
16:36:00 <felixfontein> i.e. what plugin_formatter.py does
16:36:43 <gundalow> I think just saying `Process  N  files, this may take a while...` is OK
16:36:49 <felixfontein> it takes < 10 much less than seconds for me
16:37:08 <felixfontein> (sorry for the sentence :D )
16:37:23 <felixfontein> the really slow part is sphinx, which then converts the .rst files to .html
16:37:49 <acozine> so the part that currently outputs:
16:38:09 <acozine> https://www.irccloud.com/pastebin/YtiOKgBu/make%20webdocs%20output
16:38:18 * samccann back
16:38:25 <acozine> that's sphinx working?
16:39:16 <felixfontein> no, that's plugin formatter. but that part is pretty fast, at least for me
16:40:10 <acozine> have you done `make clean` recently?
16:40:34 <acozine> it may only be fast because nothing has changed on your machine, so it isn't rebuilding any modules
16:41:03 <felixfontein> the part which prints "rendering ..." is always redoing its work, so that doesn't matter
16:41:24 <acozine> doesn't this PR remove the "rendering . . ." output?
16:41:57 <dag> yeah, generating the rst files is fast, and even faster when only a few files have to be generated
16:42:37 <dag> I need to go, my son is waiting beside me to work on his LEGO robot
16:42:39 <dag> priorities...
16:42:49 <acozine> dag: excellent, thanks for stopping by
16:42:55 <felixfontein> acozine: the PR removes the 'rendering ...' output, but the rendering still happens. after rendering, it compares the result with the file on disk (if exists), and only prints "rendering ..." if the file changed. but that's only the .rst generation step.
16:43:03 <felixfontein> dag: enjoy!
16:43:29 <felixfontein> the really slow step for documentation generation is converting the .rst files to .html (which sphinx does), but that happens later
16:43:46 <acozine> okay, I'll pull the branch again and re-test
16:44:16 <acozine> felixfontein: did you add the `for module_index, module in enumerate(module_map):` stuff to the PR?
16:44:35 <acozine> if not, I can copy it and add it in locally
16:45:00 <acozine> yikes, we're 15 minutes over
16:45:14 <acozine> time flies when you're having fun with documentation!
16:46:09 <felixfontein> ok, it is not as fast as I thought
16:46:52 <acozine> that's what I remembered - not so much how slow it was, but how it felt like nothing was happening
16:47:01 <acozine> for long enough that even I wondered if something was broken
16:47:25 <felixfontein> the .rst generation step took one minute
16:47:54 <felixfontein> now (1 1/2 minutes later) the dreaded "waiting for workers..." started
16:48:06 <acozine> ah yes, the mysteriously absent workers
16:49:22 <felixfontein> it would be nice if *that* step would have some progress information :)
16:49:34 <acozine> yes, it would
16:50:00 <acozine> though at least the ` . . . ` gives you the idea that something is going on, however slowly
16:50:19 <acozine> I need to get ready for another meeting
16:51:24 <acozine> felixfontein: if you would add the user-feedback lines as a suggestion, that would be great
16:51:28 <felixfontein> I'll hack something together and add a PR ontop of dag's PR
16:51:34 <acozine> great, thank you
16:51:57 <acozine> we'll revisit next week, unless we can merge before then
16:52:06 <acozine> thanks everybody!
16:52:15 <acozine> #endmeeting