OSRA Projects Documentation Overhaul: New Information Architecture Design Complete
Late last year, the Open Source Robotics Alliance’s (OSRA) Technical Governance Committee approved funding to begin an overhaul of the documentation for all of our projects, including ROS, ros-controls, Gazebo, and Open-RMF. We have identified this as a long-standing need and have taken the community’s input into account. Today, we are pleased to announce the completion of a significant milestone: the design of the new information architecture is complete, and we are ready to begin modifying our documentation tool chains and content to deploy it.
As the OSRA’s projects have grown in capability and complexity, improvements to the documentation needed to be made. The initiative to overhaul the documentation for each project was born from a commitment to making our software platform more accessible and easier to understand, regardless of a user’s background or experience level. Rather than continuing with our existing documentation structures and attempting to add more content to patch over gaps, we chose to start from the ground up, rethinking how the information is organised, structured, and surfaced. To ensure we have the best possible result, we have engaged 3di, a firm specializing in professional technical documentation services.
A user-centered information architecture
The result of this first phase is a new information architecture designed with our users at its core. This means the structure of our documentation will reflect how our users actually think about and interact with our software projects, and be focused on their needs when interacting with the documentation first and foremost. The goal is simple: When a user has a question, they should be able to find a clear, well-placed answer quickly and without friction.
An example user journey through the new documentation structure, used to design the information architecture.
Furthermore, the new information architecture has been designed to be adaptable to any of our projects. This allows the sharing of documentation tool chains and structures, while the content varies by project, ultimately reducing implementation and maintenance burden across all projects.
What comes next?
With the information architecture design finalised, our focus now shifts to implementation. This includes modifying our tool chains to match the new information architecture and migrating existing content to fit the new structure. As this migration work is completed, gaps where new documentation is needed will become apparent, and these gaps will be filled with newly written documentation. We will continue to work with 3di’s information architecture, toolchain, and technical writing experts to ensure that this work is performed to a high standard. We expect to see the new information architecture implemented in our current documentation, with portions of the existing documentation revised, by the end of September, 2026.
We are excited about the improvements this initiative will bring to the experience of working with the Open Robotics suite of projects. We thank you for your patience and support as we continue this important work for our entire community and ecosystem.
