Ansible Documentation update

tags: Documentation

Personas

  • Main split
    • Users vs. Creators (or maybe Playbook/Role Users, Playbook/Role Authors, Plugin/Code Creators?)
    • Next level is experience (Beginner User, Intermediate Content Creator, etc.)
    • Create a user's journey (learning tracks, roadmaps?)
    • Experience Level Personas (* Tool)
      • Beginner
      • Intermediate
      • Advanced
      • Or possibly split on familiarity with the documentation - intro to how the documentation itself works (esp. module docs)
    • good example, Apache docs for ?httpd
  • Contributors to (* Tool) Plus:
    • Collection (which has some specific bits then links to modules, plugins)
    • Module
    • Plugin (inventory, lookup, ..)
  • Maintainer of ( * Tool)
    • Collection owners
    • Community Organizers (example: Meetup Organizers, training organizers) ?
  • End-user type Personas
    • sysadmin
    • network
    • security
    • cloud
    • windows
    • database admins (heavy jinja users)
    • engineer/application developer/architect
    • automation architects - folks who design a company's automation strategy
      • overall design "best practices" how to structure git repo? How to organize inventory?

Tools, products

New Index structure

Contributor

Developer

Overview/Terminology

(Not sure if this goes here, or higher up in user-guide, maybe it's shared fragments?)

  • I want to understand the relationship between modules, plugins, roles and collections
    • I see this as the key page for context

Create

  • How to migrate an existing role into a collection ?
  • Creating a collection
    • why would you want to create a collection ?
  • What structure should a collection have, and how do I set it up
  • Creating git repository for the collection
  • Authenticating against galaxy with github to create a collection

Develop

(Maybe combine this section with the testing section)

  • What structure should a collection have, and how do I set it up
    • How do I know the structure is correct (ansible_collections/community/general/)
  • Using locally
    • How do I make ansible-playbook use my new collection

Test

  • What should I run before submitting a PR (ansible-test sanity/)
  • I want to understand the different components involved in creating and testing content
  • Which version of Ansible or Python should I test against?
  • Automatic testing with GitHub Actions

Publish

  • Collection releases
    • Manually
      • Don't do this
      • Make sure env is clear
    • How do I automatically build and release a collection (on Git tag)

Maintain

  • Life cycle
    • How to move a module or plugin to a different collection
    • How to deprecate a module
    • How to deprecate a module parameter

Partner

(Specifics about Automation Hub & Certification)

Existing dev_guide

Copy existing links (and files under rst/dev_guide and make a note of what needs updating wrt Collection)

User

Even in user docs, we should mention if you spot something that isn't clear in docs how to fix them

Notes

Select a repo