This case study is password protected
Enter the password to view.
Developer Community and API Design
Open-Source API and Integration Documentation
The Problem
Mature SOC teams often use more than one security tool, and sometimes even use security aggregators like SIEM or SOAR tools to analyze and respond to large volumes of events. For these and other nuanced workflows, users need publicly available and well-documented APIs, SDKs, and integration apps in order to port their data where they need it.
Project Goals
- Organize the documentation in a manner that users can navigate and find what they need quickly
- Standardize the documentation of APIs so they are consumable and usable no matter what team builds it
- Create patterns and templates for integrating data into other apps, even when the UI parameters vary from system to system
- Use a consistent voice in all documentation, and create a predictable cadence for publishing of materials
Process
Assessing the State of the Digital Community
The first step I took was to identify every component of the ecosystem, what overlapped, what was successful, and what was broken.
- Performed a systems audit and information architecture analysis to understand the initial state and identify the parts that were broken
- Competitive research to understand industry standards and cutting edge technology
- Workflow/service design exercise to find pain points in the API documentation delivery process and educate the org to fix or automate the people-oriented problems
- Used hackathon week to do a solo Design Sprint exercise to iterate and prototype new design solutions
Service Design Workflow Mapping
I used Service Design practices to map out both internal and external processes to examine where breakdowns were happening, what were the challenging steps, decision points, and risks, and where I could add automation or reduce complexity. This helped inform how to organize the documentation and what fixes were needed in the manual, internal processes.
Analyzing Analytics
The analytics highlighted what APIs were most or least used, how long it took users to consume the information on each page, and proved the site was heavily and frequently used. I tracked how updates, events, and announcements impacted traffic, and measured the ebb and flow over time to gauge whether we were improving the site.
Designing a New Platform
The next challenge was to take a dense, dated, and stale site and bring it up to brand standards and make it easy to use.
- Explored the user personas who would be using the site and existing content style guides to determine a correct voice and tone
- Found that users needed to understand the benefits and use cases of each API or integration
- It wasn't all technical documentation — it had to be friendly and not too dense, but also technically accurate
- Gathered input via a feedback survey to learn directly from users what challenges they were experiencing, and what new information they wanted
- Over and over, heard from users that they wanted more code snippets and examples — they didn't just want instructions, they wanted to see what possibilities the technology presented and how to get started
Card Sort Exercise
Since I was designing for developers, I used insight from the developers on my team to inform the experience. One of the first design changes was a new, consistent, easy-to-use template for API documentation. Over time we revised every piece of API documentation to follow the common template and write new content to fill it.
Low- and High-Fidelity Wireframing
For some pages we needed to make basic changes to underlying templates, which low-fidelity wireframes helped achieve. For high-visibility landing pages like the home page, I designed in iterations, taking the design to high fidelity to grab attention, make the site more modern, and tackle some of the IA issues discovered in my analysis.
CSS Annotations
I provided detailed CSS guidance to help engineers achieve my design vision.
Creating Standardization and Extensibility
Since I wouldn't always be the one writing blog posts and creating new API documents, I created reusable templates so other content creators could take over production of new instructional content.
- Created templates for API docs, integration app user guides, webpages, blogs, announcements, newsletters, events, search guide descriptions
- Heavily revised website content and documentation to use a voice that balanced concision with technical clarity, friendliness, no-nonsense, and nuance to explain the value of tools without overselling
- Restructured and rewrote critical guidance to reduce support requests
- Designed a non-marketing, technical communications strategy to revitalize a stale and neglected digital community and inform users of the innovations being built, including a recommended newsletter cadence and rules around what constitutes a blog
Designed New and Improved Integration Applications
Once we completed the website design, we addressed the integration applications housed on the site. These apps were originally built by engineers only, and the solutions were not user-friendly. My goals were to rework the installation guides to further reduce friction during setup and maintain standards across all apps — though the interfaces varied due to the products being integrated into, the language and steps for configuration maintained consistency.
Discovery Workshops
My first step in starting a new integration app initiative was leading a discovery workshop to set goals, highlight user needs, and define requirements, divided into three sections: product goals, user needs and workflow, and development requirements.
User Journey Mapping
I performed a heuristic analysis and workflow mapping exercise to assess how users configured their integration app, identified ways to reduce complexity, and visualized where certain steps took place.
Wire-Flows
I redesigned the configuration workflows and increased consistency across multiple apps and their documentation to make it easier to install, configure, and use each of them.
Challenges
- Working with a brand new, diverse team with varying communication styles and viewpoints
- Dealing with the politics and financial constraints of a large corporation in order to get website redesign approved for build
- Working in an area that didn't get a lot of visibility, having to prove the value of our designs before we could implement them
Educating the Organization
An uphill battle we faced was proving to peers and leadership the importance of an open-source API model. Many of the problems with our documentation stemmed from other engineering teams not providing the technical specifications we needed to publish rich documentation, or designers not understanding how all of the user personas interacted with APIs. I created an API persona slide deck used to present to varying audiences within the org to help broaden R&D's understanding of APIs, Integrations, and Data Delivery.
On The Spot Award — from Kylie Ebringer
eCard: Monster Effort
"Hi Lisa, Thanks for working on such a variety of things in parallel, and persisting to get a good experience for our customers. Well done working with a mix of stakeholders who have different measures of success. Thank you! — Kylie"