#ansible-docs: Ansible Contributors Summit - Documentation Breakout

Meeting started by gundalow at 20:00:27 UTC (full logs).

Meeting summary

    1. acozine and samccann are two of the Ansible upstream docs writers (samccann, 20:06:32)
    2. follow along on the etherpad for notes - https://etherpad.opendev.org/p/ansible-contributor-summit-october-2020-Docs (samccann, 20:07:23)
    3. 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)

  2. Personas (samccann, 20:13:39)
    1. how to we simplify the docsite so beginners find what they need easily, as well as advanced users/developers etc. (samccann, 20:14:47)
    2. user types - *_admin, engineer, app developer, architect. (network, security, cloud, windows) (samccann, 20:18:18)
    3. then we have experience level personas - beginner, intermediate, advanced... for each Ansible tool type (ansible, collections, ansible-lint etc) (samccann, 20:19:16)
    4. and then there is users vs developers for each of these tools and experience levels and work types. (samccann, 20:19:37)
    5. 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)
    6. 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)
    7. need better reference docs - defining the older parameters for a galaxy command for example, all in one place. (samccann, 20:28:23)
    8. 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)
    9. 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)
    10. automation consumer vs automation developer (playbook/roles creators) then beginner/intermediate/advanced (samccann, 20:39:16)
    11. 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)
    12. 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)
    13. 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)

  3. Open Floor (samccann, 20:49:15)
    1. need more docs on what filters will do (samccann, 20:50:14)
    2. 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)
    3. 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)
    4. 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)
    5. 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 (full logs).

Action items

  1. (none)


People present (lines said)

  1. samccann (43)
  2. zodbot (8)
  3. gundalow (4)
  4. abadger1999 (3)
  5. felixfontein (3)
  6. acozine (3)
  7. bcoca (2)
  8. Majisto (1)
  9. baptistemm (1)
  10. Qalthos (0)
  11. mattclay (0)
  12. jborean93 (0)
  13. jimi|ansible (0)
  14. nilashishc (0)
  15. cybette (0)
  16. relrod (0)
  17. sdoran (0)
  18. jillr (0)
  19. maxamillion (0)
  20. andersson007_ (0)
  21. shertel (0)
  22. nitzmahone (0)
  23. webknjaz (0)
  24. matburt (0)
  25. sivel (0)
  26. mkrizek (0)
  27. thaumos (0)
  28. Shrews (0)


Generated by MeetBot 0.1.4.