Docs Portfolio
Welcome to my portfolio! Most of these samples are from braze.com/docs, where I was the Documentation Manager. On this page, you’ll see six samples, each of which focus on different audiences with different goals:
API Swagger Spec
IDFA Collection Reference Article (iOS)
Postman Setup Guide
Setting Up IPs & Domains (Email)
Landing Page/Guided Reading
Release Notes
1 API Swagger Spec
Audience:
Developers
SME:
Engineering Team, segmented by sub-team based on product.
About:
Braze maintained all of its API documentation from a single spec. However, endpoints are detailed at length in singular pages (Markdown version as last edited by me) to provide additional reference information and allow for the searching and quick find of individual endpoints and their parameters.
Looking Back…
I would have loved to have structure the “two-sided” API docs depicted by both Bolt and Stripe - it got the most support by engineers, but in the end was overruled due to our engineer’s bandwidth at the time and the deadlines set around the restructure of the API docs section.
Side note: There used to be a page where users could search for individual endpoints from a single location, but it appears to either be down or broken, and I can’t show you it because of that.
2 Reference Docs: Developers & Marketers
Audience:
Developers & Marketers
Both audiences need this documentation to both make decisions on and prepare for the initial integration/set up of the product. Because of that, I included enough information that, in the event a developer needed to integrate IDFA because of certain dependencies, they would have the content to send directly to their marketer/requester to detail the reasoning behind wanting to or not wanting to integrate with IDFA collection.
SME:
iOS Product Manager and Lead iOS Developer
About:
The iOS section needed an article that enabled but also discouraged a “minimal data intake” approach to integration, because data collection is an important piece of the product, we continuously present the “stakes” of not integrating with IDFA collection capabilities, which removes many of the “perks” of a full Braze integration. However, it was necessary to provide this for users who needed to comply with certain GDPR or stricter local data collection laws.
Looking Back…
I would probably look for a way to structure the document from one perspective/purpose or another, and either present it within a “Collaborating with your engineer/marketer” section, or keep it as a single page and allow readers to select their perspective from a tab.
3 Tool Setup Guide
Audience:
Developers, specifically those new to Postman. Some Marketers and Internal Braze Users new to APIs.
SME:
Engineering Team & Client Success Team Members.
About:
Braze has a great number of API users and, though it would be ideal to only manage the documentation in a single place, the breadth of customers actually led to our belief that it was better to also manage it in Postman for ease of use. This was a pretty simple article and even now it’s a great agnostic reference for learning more about APIs.
Looking Back…
I believe this content, while great as an article, also deserved a video of some sort to help demonstrate. In the future, I would pair it with a video walkthrough.
4 Simple How-To
Audience:
Marketers
SME:
Product Manager of Email and Onboarding & Integrations Team.
About:
This is a great example of a simple How-To article, with a simple, but necessary “orientation” note at the top, that orients users to the information they’re about to process and ensures they know what they should be doing in this article and what is expected of them.
Looking Back…
I would add numbers to articles and have a clearer “this is a step by step process” inside the greater Email Setup section..
5 Landing Page / Guided Reading
Audience:
Marketers
SME:
Customer Education Team.
About:
This page was constructed as a more user-friendly index that allowed marketers with different use cases to quickly navigate and fine the information they needed to get started quickly.
Looking Back…
I would have loved to have more closely worked with the Customer Ed team to create supplemental courses that went with these materials, beyond just having “documentation paths.”
6 Release Notes
Audience:
Marketers
Developers could see relevant notes to them in the SDK Changelogs.
SME:
Product Managers, Marketing/Customer Comms, & Customer Success Team Members, as needed.
About:
The Release Notes section was always the most fun for me - it was a great opportunity to be creative and collaborate with a multitude of teams and bring in their creativity and messaging, as well.
This section was very much treated like a library in itself - we liked to link directly to relevant sections or articles where we can.
Looking Back…
I wouldn’t do anything differently! I’m happy to see that Braze still uses my “Most Recent” landing page with almost the same information and structure and links to other pages! Very proud of this section as a whole.