Adding documentation to an award-winning interface
Putting the Topcoat on Topology
The fruitful results of a highly-requested effort
What is the Topology view and why is it important?
As stated in the Openshift documentation, “The topology view provides a visual representation of all the applications within a project, their build status, and the components and services associated with them.”
In 2020, Topology view won the Community Choice Prize in the Core77 Design Awards, where it was described as “a thoughtfully designed interface in the developer perspective of the OpenShift web console. It provides a visual representation of the application structure, which makes it easier for developers to focus on the information that matters most.”
What products use it right now?
OpenShift, Ansible, Kiali, and Advanced Cluster Security (ACS)
Who has been asking for the docs?
A lot of people and a lot of products, from OpenShift to Ansible to Kiali to ACS.
Why was it important to have topology documentation?
It was so highly requested and sought after. Over the past few years, our resident topology expert and development lead, Jeff Phillips, fielded many questions and demoed Topology on numerous occasions to various product teams and developers.
One consistent question was “How do I implement Topology view? Is there any documentation for it?” To which the answer was “Not yet!”
Until now…
We identified this as a task that needed to be done within the Patternfly workspace since Topology is built with Patternfly styles and components. Once we decided that the Topology documentation would live in its own special nav item on patternfly.org, we started building.
Nodes, Connectors, and Groups… Oh my! Documenting uncharted territory.
What do you do when you need to document territory that you yourself are unfamiliar with?
Lewis and Clark faced a similar challenge two hundred years ago… Don’t panic!
As I asked questions through my deep dive into the codebase, nodes started connecting in my brain and in the demos. I found that my first encounter with the topology codebase was a big advantage to this important effort, because, like anyone else who seeks out documentation, I was able to approach it with a pair of fresh eyes and build from the ground up. As a result, we were able to create clear and comprehensible documentation for users who are seeing topology code for the first time.
How did we do it? An MVP is the MVP 🏆
With a baseline implementation, less is more! Creating a minimum viable product in the form of a demo is what set the foundation for the rest of the demos and documentation.
Building on demos incrementally optimized the implementation effort, because we could distinctly introduce additional functionality. As a result, consumers can easily compare the demos and identify where code was added to support new features.
So… how do I implement Topology view? Is there any documentation for it?
Yes! You can see the topology documentation here.
Have a story of your own? Write with us! Our community thrives on diverse voices — let’s hear yours.
