20:00:27 <gundalow> #startmeeting Ansible Contributors Summit - Documentation Breakout
20:00:27 <zodbot> Meeting started Thu Oct 15 20:00:27 2020 UTC.
20:00:27 <zodbot> This meeting is logged and archived in a public location.
20:00:27 <zodbot> The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot.
20:00:27 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
20:00:27 <zodbot> The meeting name has been set to 'ansible_contributors_summit_-_documentation_breakout'
20:00:58 <samccann> join on bluejeans as well -  https://bluejeans.com/324026273
20:01:02 <felixfontein> o/
20:01:23 <samccann> \o
20:02:43 <acozine> \o/
20:05:14 <samccann> #chair abadger1999 acozine cybette jborean93 jillr jimi|ansible matburt mattclay maxamillion mkrizek nilashishc nitzmahone Qalthos relrod samccann sdoran shertel Shrews sivel thaumos webknjaz andersson007_ felixfontein
20:06:06 <samccann> #topic intros
20:06:15 <samccann> feel free to add an intro here if you want.
20:06:32 <samccann> #info acozine and samccann are two of the Ansible upstream docs writers
20:06:47 <baptistemm> sorry I won't attend it's a bit late for me now
20:07:12 <acozine> sorry to miss you
20:07:13 <samccann> no worries. See the etherpad later if you are interested in what was covered.
20:07:23 <samccann> #info follow along on the etherpad for notes - https://etherpad.opendev.org/p/ansible-contributor-summit-october-2020-Docs
20:09:45 <samccann> #info general info on how to contribute to Ansible docs - https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#contributing-to-the-ansible-documentation
20:11:40 <Majisto> Mitchell is here
20:11:55 <samccann> #chair Majisto
20:11:58 <samccann> welcome!
20:11:58 <felixfontein> hi Mitchell :)
20:12:06 <samccann> hmm... that didn't seem to work.
20:12:11 <samccann> but welcome!
20:12:53 <abadger1999> gundalow: You need to chair people :-)
20:13:06 <abadger1999> (otherwise samccann won't be able to set topic, chair new people, etc)
20:13:14 <felixfontein> abadger1999: I think most are already
20:13:28 <samccann> aaah that's why
20:13:39 <gundalow> #chair abadger1999 acozine cybette jborean93 jillr jimi|ansible matburt mattclay maxamillion mkrizek nilashishc nitzmahone Qalthos relrod samccann sdoran shertel Shrews sivel thaumos webknjaz andersson007_ felixfontein
20:13:39 <zodbot> Current chairs: Qalthos Shrews abadger1999 acozine andersson007_ cybette felixfontein gundalow jborean93 jillr jimi|ansible matburt mattclay maxamillion mkrizek nilashishc nitzmahone relrod samccann sdoran shertel sivel thaumos webknjaz
20:13:39 <samccann> #topic Personas
20:13:57 <abadger1999> gundalow: thanks :-)
20:14:03 <gundalow> #chair Majisto
20:14:03 <zodbot> Current chairs: Majisto Qalthos Shrews abadger1999 acozine andersson007_ cybette felixfontein gundalow jborean93 jillr jimi|ansible matburt mattclay maxamillion mkrizek nilashishc nitzmahone relrod samccann sdoran shertel sivel thaumos webknjaz
20:14:10 <gundalow> abadger1999: thanks,
20:14:47 <samccann> #info how to we simplify the docsite so beginners find what they need easily, as well as advanced users/developers etc.
20:16:51 <samccann> The personas are listed in the etherpad. Discussing if windows should be a separate category from sysadmin (most agree).
20:18:18 <samccann> #info user types - *_admin, engineer, app developer, architect. (network, security, cloud, windows)
20:19:16 <samccann> #info then we have experience level personas - beginner, intermediate, advanced... for each Ansible tool type (ansible, collections, ansible-lint etc)
20:19:37 <samccann> #info and then there is users vs developers for each of these tools and experience levels and work types.
20:19:50 <samccann> that.. is a lot.. of variety ...;-)
20:20:10 <samccann> How to we keep from duplicating all that info, but still have good access for the right info for each role
20:23:55 <samccann> #info also considering where we need more `How do I...?` docs... like how do I questions on stack overflow. Maybe need an Ansible cookbook of common things everyone wants to do.
20:26:57 <samccann> #info also need more beginner details on how to use jinja templates/filters and can't find all of them that are built in (some in jinja, some in ansible)
20:28:23 <samccann> #info need better reference docs - defining the older parameters for a galaxy command for example, all in one place.
20:30:07 <samccann> #info some of the docs seem to be based/organized based on the source code where the docs come from, not based on how a user would need to learn it. See apache http docs for a better example
20:36:19 <samccann> #info consider if we should have an 'intro to the docs' section to help people learn how it is organized so they can find what they need more easily.
20:39:16 <samccann> #info automation consumer vs automation developer (playbook/roles creators)  then beginner/intermediate/advanced
20:42:29 <samccann> #info automation architect - responsible for building the platform and communities around how to create content (content style guides, how to organize git repos.. when to use roles vs playbooks vs collections)
20:47:57 <samccann> #info some of the tools (aka ansible-lint etc) may not be used by say an automation consumer. Need to answer when should I use molecule... ansible-base...etc.
20:48:49 <samccann> #info while an ansible-lint docs needs to exist, we have a separate need for 'I'm a collection developer - what do I need to know about ansible-lint to get my stuff imported etc)
20:49:15 <samccann> #topic Open Floor
20:49:26 <samccann> here's where you can bring up anything you want about docs
20:49:53 <acozine> Open Floor!
20:50:14 <samccann> #info need more docs on what filters will do
20:51:26 <samccann> #docs have good 'discussion' and some examples... but there is no concise reference (definition) of what each does. Stack overflow is filling this info in for us
20:51:37 <samccann> heh that didn't work
20:51:47 <samccann> #info have good 'discussion' and some examples... but there is no concise reference (definition) of what each does. Stack overflow is filling this info in for u
20:51:54 <samccann> #undo
20:51:54 <zodbot> Removing item from minutes: INFO by samccann at 20:51:47 : have good 'discussion' and some examples... but there is no concise reference (definition) of what each does. Stack overflow is filling this info in for u
20:51:58 <samccann> #info have good 'discussion' and some examples... but there is no concise reference (definition) of what each does. Stack overflow is filling this info in for us
20:53:50 <samccann> #info difficult for users to have to read ansible for ansible filters, then read jinja for jinja filters. Maybe add a list of common jinja filters that are used a lot by ansible users (with links)
20:59:09 <samccann> #info add a list of common jinja filters, or turn references to jinja filters to an intersphinx link within the text to link over to that in the jinja docs.
21:11:21 <bcoca> samccann hope to have something ffor 2.11 that allows using ansible-doc/builging the same as for other plugin types
21:11:37 <samccann> #info please subscribe to the Ansible BullHorn to keep up with high-level changes in Ansible. We'll use this to communicate progress on the issues discussed here today - https://docs.ansible.com/ansible/devel/community/communication.html#the-bullhorn
21:11:40 <bcoca> only issue is 'available jinja2' can make things vary from docs we add/overlay vs what jinja2 version has available
21:12:45 <samccann> #endmeeting