Topics include Supply Chain Security, Microservice Management, Neat Tricks, and Contributor insights.
The following information is submitted by the Ortelius open-source community to be selected for the Google Season of Docs.
Ortelius is a microservice management platform that versions and tracks microservices, their consuming applications, ownership, blast radius and where they have been deployed with all critical deployment metadata. By centralizing and tracking detailed configuration data, Ortelius provides you a proactive view of how your microservice architecture is changing overtime across all clusters. Ortelius is a new incubating project under the Continuous Delivery Foundation.
The existing Ortelius documentation has a substantial amount of content which works well for someone who has a deep technical understanding and simply needs the documentation for reference. The core problem with the documentation is that it is not usable for developing a skill set in Ortelius. The result is new users of Ortelius struggle with on-boarding and adoption of the solution.
The current documentation has a good structure, but much of the content is presented in isolation. In addition, there are gaps/weaknesses around clarity, completeness of information, and is generally ambiguous in terms of for whom the information is written. The result is documentation that is not always suitable for the intended audience. In particular, there is a bit too much assumed knowledge within the documentation which does not facilitate learning or improving the user’s skill set. In order to improve the onboarding of Ortelius, this primary documentation issue must be addressed.
Ortelius Documentation Repository - https://github.com/ortelius/ortelius-docs
The scope of the Ortelius Project for GSoD is to address specific areas related to on-boarding of new users in terms of their ‘first hour.’ We will seek a technical writer who can enhance the documentation to address the persona weakness described above. This will include identifying which personas are consuming the documentation, with a view of aligning documentation content accordingly.
To simplify the adoption of Ortelius, the technical writer will be tasked with documenting a clear beginner path with the deeper technical material being used as references. There is currently a starting point for this effort in the installation/getting started sections, but this information should be more prominent and framed within the larger context of what value Ortelius is providing.
By enhancing the documentation as a skill building reference, we can improve the end user experience from the first hour through full implementation. In addition, end users will be provided basic insights on how Ortelius solves core issues common in microservice management.
This project will NOT include adding new documentation for new features or expanding existing technical documentation around lower level subjects such as APIs, Actions or Plug-ins. These topics are too low level and are not needed for an End User’s ‘First hour’ which is the focus of this project.
The Ortelius community will identify 3 members from the community to review the updated documentation to provide ongoing feedback if the goal - clarity for new end users - is are being achieved and provide course correction of needed.
Based on the existing content, the following time estimates are assumed:
| Budget Item | Amount | Running Total | Justification/Notes |
|---|---|---|---|
| Persona Selection | $300 | $300 | |
| Core Documentation Updates | $6,000 | $6,300 | Ortelius Doc team to provide ongoing feedback. |
| Two Tiers | $2,250 | $8,550 | Ortelius Doc team to provide ongoing feedback |
| Doc. Reorganization | $750 | $9,300 | May not be required - depends on the extensiveness of core updates. |
Total Budget $9,300
The Ortelius Team members have varied experience with developing technical content and working with technical writers. Tracy Ragan, project administrator, was the primary contributor of the existing technical documentation. In her work experience, she has hired technical writers to expand on and organize existing documentation for ease of use and readability. As part of the submittal for this project, a technical writer reviewed the existing Ortelius documentation and made specific recommendations for participation in GSoD.