Robot Framework is a generic open source automation framework. It can be used for test automation and robotic process automation (RPA). Robot Framework is open and extensible – it can be integrated with virtually any other tool to create powerful and flexible automation solutions.
Robot Framework is supported by the Robot Framework Foundation. Robot Framework Foundation is a non-profit consortium that fosters the growth of Robot Framework. It was founded by companies with a common interest to ensure the development of Robot Framework now and in the future.
Robot Framework was initially developed at Nokia Networks around 2005. When Nokia decided to drop the development, the Foundation was established by a group of user companies who believed in the tool and wanted to continue the funding. Hence, in 2015 the Foundation took over the development and maintenance and the number of Foundation members has grown from the original 7 to 50+ as of today. Moreover, we have a vibrant community in Slack and hundreds of thousands of users all over the globe.
Our User Guide is one of the main resources and during the past 12 months some 500 thousand people have visited that page. Unfortunately, the current User Guide is not up to par and we would need help to update it in order to better serve our community and the people who use our great tool.
There are few issues with the current User Guide.
The content could be modernized. Some of the examples, although still correct, are from the very early days of the project.
The structure is now a mix of technical guide (manual) and a quick start guide with examples. We have created a separate "Docs" site for examples and more hands-on material and we would see fit to move the examples from the User Guide there, making the User Guide a more of a technical manual. Overall, we see that the User Guide structure should be revised and possibly re-organized and the document re-written at least partly.
The User Guide is currently hosted as a static HTML page under GitHub pages. Part of the overall User Guide modernization project is moving it to a dedicated documentation platform that natively supports search, glossary, showing documentation for different Robot Framework versions, and so on. Alternatives include Docusaurus, that we use with the aforementioned Guides, and Read the Docs, that is used with the API documentation.
Deciding the documentation platform needs to be done in collaboration with the Robot Framework core development team that will use the said platform in their daily work afterwards. A part of this is making sure that the latest documentation is automatically build after changes. Setting the platform and needed integrations can be considered a separate project and the technical writer does not need to be responsible on it.
The User Guide should be more visually appealing. The User Guide can be a bit off-putting for new users just learning about the tool and landing on the page. Part of the project is making the visuals more appealing and the overall document more approachable.
All of the above mentioned changes would help us to better serve the Robot Framework users, whether beginners or advanced, to find what they are looking for and solve their Robot Framework issues.
The update and restructure Robot Framework User Guide project will:
- audit the existing User Guide and evaluate to what extent we need new content and how to improve the current content
- write new content and update existing content of the User Guide for the relevant parts identified
- evaluate and change the structure of the User Guide
- bring the new User Guide onto the selected documentation platform
In the project team, we will have a project manager, community members, our webmaster and our main developer to support the technical writer.
We estimate it takes 6 months to complete the project.
Overall, the project is successful if we have a clearly structured updated User Guide in a visually appealing format with a clear distinction between the User Guide and Docs.
In order to know if people like the new User Guide, we should conduct a community survey or add questions about it in our bi-annual survey.
Moreover, one indication of a successful project could be the reduction of the bounce rate on the User Guide page, which is currently 36%. Some of this comes from factors outside of the project scope, but part of the bounce rate can be due to the structure, visuals and other attributes of the current User Guide, which does not invite people to stay on the page.
The project itself will take approximately six months to complete. Once the technical writer is hired, we'll spend a few weeks on the orientation, then move onto the audit phase, and then spend a few months on creating the new User Guide content and lastly getting that into Docusaurus.
| Tentative dates | Action Items |
|---|---|
| May | Orientation |
| June - August | Audit existing documentation and create friction log |
| September - October | Create User Guide |
| November | Project completion |
| Budget item | Amount | Running Total | Notes/justifications |
|---|---|---|---|
| Technical writer audit, update, test, and publish new User Guide | 10500.00 | 10500.00 | Let’s hope this is enough. |
| Web development | 1500.00 | 12000.00 | Our webmaster’s work to have help with Docusaurus |
| Main developer | 1500.00 | 13500.00 | Our main developer to give introduction to the current Docs; help with the new ones |
| Project implementation in Docusaurus | 1500.00 | 15000.00 | Getting the new updated User Guide to Docusaurus |
| TOTAL | 15000.00 | USD |
The main developer, who will also be part of the work group, has written the current User Guide and can help with any questions and also can provide an introduction to the topic as well as other help with the current documentation and transition to the new format.
Moreover, one of the work group members is the main author of our Docs, and is also available to help to transform and implement the updated User Guide content to Docusaurus platform. Lastly, project management and administration is provided by the Executive Director of the Robot Framework Foundation.