AWX Operator Documentation, What’s New? - Ansible Contributor Summit 2023

AWX Operator Documentation, What’s New? ~30 min The new AWX Operator Docs is live. Join us in discussing how we used the Community Writers’ effort to make this a success—the process, contributions, and how everything summed up to the new documentation.

This is a presentation for the Ansible Contributors Summit Durham 2023.

Link to track the documentation progress:
https://github.com/ansible/awx-operator/issues/1360
https://ansible.readthedocs.io/projects/awx-operator/index.html

Transcript

1. Ansible Contributor Summit ‘23 AWX Operator Documentation, What’s New? Presented By Desmond Obisi
2. Presentation Agenda These are the following topics to be discussed in this presentation What is AWX Operator? Overview of AWX Operator to make sure everyone is acquainted with the topic of discuss. Why Documentation Matters DIscussing why documentation matters in building good and usable software. Old Documentation Challenges Challenges users faced while using the old documentation Community Writers Effort About the Community Writer Forum and how little contributions cause great changes that matters Documentation Process/Key Improvements The thought process, breakdown, contributions, key improvements and all that went into forming the new documentation Feedbacks and Future Iterations Feedbacks we have gotten, Iterations that are in plans to make the documentation better Moving On… How the Writers Community can help documentation efforts, support needed and Q/A
3. What is AWX Operator AWX Operator is an Ansible AWX operator for Kubernetes built with Operator SDK and Ansible. Simply put, it is a tool use to add or run Ansible AWX in kubernetes applications. Ansible AWX on the other hand provides a web-based user interface, REST API, and task engine built on top of Ansible. It is one of the upstream projects for Red Hat Ansible Automation Platform.
4. Why Documentation Matters • Documentation ensures open-source software is accessible to all, catering to users of varying expertise and backgrounds. • Documentation serves as a valuable resource for newcomers, easing their learning curve and enhancing the onboarding process. • Documentation empowers users to independently troubleshoot issues and find solutions, reducing the need for external support. • Documentation enforces best practices and coding standards, maintaining consistency within the project. • Documentation promotes transparency and collaboration by documenting decisions, project history, and roadmaps. • Documentation preserves project knowledge, acting as a reference point for future contributors and preventing knowledge loss. • Documentation is essential for long-term sustainability, attracting and retaining contributors while ensuring project growth and relevance.
5. Old Documentation Challenges • Difficulty Finding Topics: Users often found it hard to locate specific information within the documentation. • Overloaded README: Information was overloaded in the project's README, making it cluttered and hard to follow. • Poor Navigation: The documentation lacked an intuitive navigation structure, making it challenging for users to find what they needed. • Dispersed Information: Valuable information was not centralized but scattered throughout the codebase, causing confusion and inefficiency for users. • Lack of Structure: The documentation was not grouped or structured, making it difficult to understand and follow a logical flow.
6. Community Writers Effort The Writers community, a group formed by people passionate about improving documentation in OSS has continued to thrive in the Ansible Ecosystem in the past few years. Some important details about the Writers Community efforts towards documentation at Ansible: • About 60 PR raised for documentation fixes and improvements in the Ansible Community. • About 27 PR reviewed across documentations in the Ansible Community. • Worked with the Documentation team to migrate Ansible AWX Operator documentation to a new doc website. • And more to come…
7. Sutapa set up the MkDocs for the new documentation. A breakdown into sections was done to group the docs. Documentation Process An Issue was created to register the pain point and track changes. Sandra McCann, Desmond, Christian Adams reviewed. After review, the first version was built and pushed live Desmond, Oluchi and Sandra McCann worked on this Issue MKDocs Breakdown Review Build Migration
8. Key Improvements Structured Layouts Better User Experience Consolidated Information New Documentation Updated Examples
9. Feedbacks and Future Iterations • Adding translation if needed. • Adding examples(a walkthrough of a full setup) a total beginner can follow. • Merge some of the sections into a page (the ones with few sentences) Future Iterations Feedbacks
10. Moving On… Moving on, the Writers Community: • Will continue contributions to Ansible documentations • Will grow the community and host documentation workshops for people interested in OSS contributions • Take initiatives as much as we can to build better documentation and guides in the community.
11. CREDITS: This presentation template was created by Slidesgo, and includes icons by Flaticon, and infographics & images by Freepik Thank You!