20:00:27 #startmeeting Ansible Contributors Summit - Documentation Breakout 20:00:27 Meeting started Thu Oct 15 20:00:27 2020 UTC. 20:00:27 This meeting is logged and archived in a public location. 20:00:27 The chair is gundalow. Information about MeetBot at http://wiki.debian.org/MeetBot. 20:00:27 Useful Commands: #action #agreed #halp #info #idea #link #topic. 20:00:27 The meeting name has been set to 'ansible_contributors_summit_-_documentation_breakout' 20:00:58 join on bluejeans as well - https://bluejeans.com/324026273 20:01:02 o/ 20:01:23 \o 20:02:43 \o/ 20:05:14 #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 #topic intros 20:06:15 feel free to add an intro here if you want. 20:06:32 #info acozine and samccann are two of the Ansible upstream docs writers 20:06:47 sorry I won't attend it's a bit late for me now 20:07:12 sorry to miss you 20:07:13 no worries. See the etherpad later if you are interested in what was covered. 20:07:23 #info follow along on the etherpad for notes - https://etherpad.opendev.org/p/ansible-contributor-summit-october-2020-Docs 20:09:45 #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 Mitchell is here 20:11:55 #chair Majisto 20:11:58 welcome! 20:11:58 hi Mitchell :) 20:12:06 hmm... that didn't seem to work. 20:12:11 but welcome! 20:12:53 gundalow: You need to chair people :-) 20:13:06 (otherwise samccann won't be able to set topic, chair new people, etc) 20:13:14 abadger1999: I think most are already 20:13:28 aaah that's why 20:13:39 #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 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 #topic Personas 20:13:57 gundalow: thanks :-) 20:14:03 #chair Majisto 20:14:03 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 abadger1999: thanks, 20:14:47 #info how to we simplify the docsite so beginners find what they need easily, as well as advanced users/developers etc. 20:16:51 The personas are listed in the etherpad. Discussing if windows should be a separate category from sysadmin (most agree). 20:18:18 #info user types - *_admin, engineer, app developer, architect. (network, security, cloud, windows) 20:19:16 #info then we have experience level personas - beginner, intermediate, advanced... for each Ansible tool type (ansible, collections, ansible-lint etc) 20:19:37 #info and then there is users vs developers for each of these tools and experience levels and work types. 20:19:50 that.. is a lot.. of variety ...;-) 20:20:10 How to we keep from duplicating all that info, but still have good access for the right info for each role 20:23:55 #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 #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 #info need better reference docs - defining the older parameters for a galaxy command for example, all in one place. 20:30:07 #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 #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 #info automation consumer vs automation developer (playbook/roles creators) then beginner/intermediate/advanced 20:42:29 #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 #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 #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 #topic Open Floor 20:49:26 here's where you can bring up anything you want about docs 20:49:53 Open Floor! 20:50:14 #info need more docs on what filters will do 20:51:26 #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 heh that didn't work 20:51:47 #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 #undo 20:51:54 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 #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 #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 #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 samccann hope to have something ffor 2.11 that allows using ansible-doc/builging the same as for other plugin types 21:11:37 #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 only issue is 'available jinja2' can make things vary from docs we add/overlay vs what jinja2 version has available 21:12:45 #endmeeting