===================================================================
#ansible-docs: Ansible Contributors Summit - Documentation Breakout
===================================================================


Meeting started by gundalow at 20:00:27 UTC. The full logs are available
at
https://meetbot.fedoraproject.org/ansible-docs/2020-10-15/ansible_contributors_summit_-_documentation_breakout.2020-10-15-20.00.log.html
.



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)
* Personas  (samccann, 20:13:39)
  * how to we simplify the docsite so beginners find what they need
    easily, as well as advanced users/developers etc.  (samccann,
    20:14:47)
  * user types - *_admin, engineer, app developer, architect. (network,
    security, cloud, windows)  (samccann, 20:18:18)
  * 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)

* Open Floor  (samccann, 20:49:15)
  * 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)

Meeting ended at 21:12:45 UTC.




Action Items
------------





Action Items, by person
-----------------------
* **UNASSIGNED**
  * (none)




People Present (lines said)
---------------------------
* samccann (43)
* zodbot (8)
* gundalow (4)
* abadger1999 (3)
* felixfontein (3)
* acozine (3)
* bcoca (2)
* Majisto (1)
* baptistemm (1)
* Qalthos (0)
* mattclay (0)
* jborean93 (0)
* jimi|ansible (0)
* nilashishc (0)
* cybette (0)
* relrod (0)
* sdoran (0)
* jillr (0)
* maxamillion (0)
* andersson007_ (0)
* shertel (0)
* nitzmahone (0)
* webknjaz (0)
* matburt (0)
* sivel (0)
* mkrizek (0)
* thaumos (0)
* Shrews (0)




Generated by `MeetBot`_ 0.1.4

.. _`MeetBot`: http://wiki.debian.org/MeetBot