Meeting started by gundalow at 20:00:27 UTC
(full logs).
Meeting summary
acozine and samccann are two of the Ansible
upstream docs writers(samccann,
20:06:32)
follow along on the etherpad for notes -
https://etherpad.opendev.org/p/ansible-contributor-summit-october-2020-Docs(samccann,
20:07:23)
general info on how to contribute to Ansible
docs -
https://docs.ansible.com/ansible/latest/community/documentation_contributions.html#contributing-to-the-ansible-documentation(samccann,
20:09:45)
then we have experience level personas -
beginner, intermediate, advanced... for each Ansible tool type
(ansible, collections, ansible-lint etc)(samccann,
20:19:16)
and then there is users vs developers for each
of these tools and experience levels and work types.(samccann,
20:19:37)
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.(samccann,
20:23:55)
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)(samccann,
20:26:57)
need better reference docs - defining the older
parameters for a galaxy command for example, all in one
place.(samccann,
20:28:23)
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(samccann,
20:30:07)
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.(samccann,
20:36:19)
automation consumer vs automation developer
(playbook/roles creators) then
beginner/intermediate/advanced(samccann,
20:39:16)
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)(samccann,
20:42:29)
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.(samccann,
20:47:57)
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)(samccann,
20:48:49)
need more docs on what filters will do(samccann,
20:50:14)
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(samccann,
20:51:58)
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)(samccann,
20:53:50)
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.(samccann,
20:59:09)
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(samccann,
21:11:37)