I wrote and edited Sensu’s documentation, including API documentation, references, and user guides. I also maintained and improved the Hugo docs site and reworked the information architecture.
Sensu is an agent-based monitoring and observability tool that you install on your organization’s infrastructure. Sensu users can collect status events and metrics, configure context-rich alerts that improve incident response and reduce alert fatigue, and transmit collected data to long-term storage.
I wrote and edited Sensu’s documentation as the sole technical writer for 3 years. I also maintained the Hugo docs site, reworked the docs site’s information architecture, redesigned the docs landing page, notified customers of new and updated documentation, and developed Katacoda scenarios to help people learn Sensu.
Sensu’s documentation is published at https://docs.sensu.io/. Here are some examples that demonstrate my work:
I worked with Sensu’s engineers, product manager, and support and sales teams to identify documentation needs and track down source material. OpenAPI Specification files and the API source code were available as source material for the API documentation, and I tested and confirmed API calls and responses with Postman. To develop and test the docs as I worked, I ran Sensu in Vagrant boxes and Docker containers.
When someone else on the Sensu team drafted docs content, I helped them test and edit it as well as find the right spot for it within the docs site.
The docs were deployed to a Hugo site. I did not create the site, but I maintained it and added improvements as needed:
To support Sensu’s transition to a single product, I completed a project to rework the docs site’s information architecture so that it aligned with the new product and the Sensu Observability Pipeline concept. I followed the approach described in Everyday Information Architecture by Lisa Maria Martin to complete an audit, categorize the content, and sort out the structure and navigation. Then, I worked with my boss to refine the new structure and incorporate feedback from every team.
After the plans were finalized and approved, I created a Trello board to organize, prioritize, and track the reorganization work. I broke the work down into logical groups of tasks and created a Trello card for each task to make sure I didn’t overlook anything—every page in the docs was affected. As I worked, the Trello board was handy for quickly communicating the project status. As I completed each group of tasks, I used Slack to explain the changes internally and posted to the Sensu Community Forum to explain the changes to our customers.
In the course of the information architecture project, I used Lucidchart to design and create an interactive SVG image of the Sensu Observability Pipeline to give customers a mental model of how Sensu works. Readers can click any element in the pipeline image to get more information. I also set up a simple JavaScript button to simulate a “tour” through each element in the observability pipeline.
As the final piece of the project, I redesigned the docs landing page. We wanted the landing page to give people a quick overview of Sensu Go and demonstrate the breadth of documentation we offered. I wireframed the landing page in Lucidchart and again worked with my boss and other stakeholders to adjust the design until everyone was satisfied. I worked with a contractor to implement the new landing page.
I used these tools in the course of my work on the Sensu documentation: