Gaps and Obstacles in Developing Collections with ADT: Lack of Clear ADT User Guidance and Documentation

[Andersson007]

The context: we are now working on the Improve the Partner Certification Experience ANSTRAT-1330 .
To complete the Document the gaps and obstacles on collection workflow story, every community engineering team member independently went through a typical collection development workflow: created a collection with a module from scratch, configured GitHub including CI, published it on Galaxy, etc. trying to use Ansible development tools as much as possible and reflecting their experiences in the Obstacles and issues found with ADT Google doc along the way.

This issue summarizes the challenges and obstacles encountered by the Community Engineering team while developing collections using ADT. Tool-specific feedback will go to corresponding repositories.

Lack of Clear ADT User Guidance and Documentation

Obstacle: Users frequently encounter difficulties due to insufficient in-tool guidance and a lack of comprehensive, easily accessible documentation for various functionalities and workflows.

General spotted patterns to improve:

• ADT documentation is highly fragmented and written entirely from the perspective of how to use the tools rather than how to achieve a goal.
• ADT documentation also has lots of missing information and assumptions, both about the knowledge of the user and their objectives.
  • Possible solution: it should be rewritten and become consistent (how to achieve a goal) for a reader who’s not an experienced collection developer/maintainer.
• If ADT provides an opinionated path, then it is essential to explain those opinions to the user. There are few guardrails after scaffolding to maintain the proper state of the collection. We had to do a bit of hacking to get both integration and unit tests to work. Without more detailed documentation ADT is simply giving collection developers a lot of rope to hang themselves with. It gives you a solid starting point, but then leaves you to make your own decisions based on guesswork.
• No path to really onboard existing automation content into Dev Tools workflows. The Dev Tools workflow assumes you’re starting from scratch.
• Lack of cohesive path between community docs and ADT docs. How do you move from writing a module or plugin to creating a collection with ADT?
• There is too much friction when you get too far following “docs.ansible.com” then switch over to Dev Tools. There aren’t any smooth ramps between community docs and Dev Tools.
• There should be a document that gives the opinionated flow so ADT users wouldn’t have to skip around so much.

Ansible Dev Tools docs:

• Docs are hard to follow due to too many different navigation options and inconsistencies in workflows between the left-hand and tob-bar navigation bars.
  • Possible solution: re-think and re-design the navigation bars for better UI/UX.
• The documentation for the deploy phase required jumping around multiple docsites to complete this.
  • Possible solution: create a downstream document that gives the opinionated flow so ADT users wouldn’t have to skip around so much.
• The Building a collection step assumes you have ansible VSCode extension installed but nothing in the install says this is a prerequisite.
  • Should it really be a prerequisite? People use many different IDEs / text editors. Not everybody is happy to adopt another IDE.
• ADT docs could do with either a few steps on generating the changelog or a pointer to the antsibull-changelog docs. It’s not clear that ADT scaffolding provides the config.yml file for us so no need to recreate it