Organization & Role

Heap is a digital analytics platform. As their founding documentation strategist, I’m responsible for the user experience, information architecture, content strategy, and all content within the Help Center and developer/API docs.

Project & Problem

When I first joined Heap, there was no singular owner of Heap’s documentation, which meant there was no defined process for folks to request doc changes.

Within my first 90 days, I created a simple, easy-to-use, and scalable docs request process. This allowed everyone at Heap to easily file and track new requests, and allowed me to manage and prioritize these requests in a transparent way.

Approach

Gathering Feedback

During my first month, I scheduled a series of coffee chats with members of Support, Product, Marketing, Account Management, Professional Services, and Customer Education (essentially, anyone who had ever been involved with docs) to gather feedback on how we can collaborate.

Knowing I needed to get a docs request process up and running ASAP, I asked about:

• Their most urgent pain points with the existing documentation.
• How they envision the docs strategist (me) addressing these pain points. 
• What project management and collaboration tools their team uses.  
• What they would like in a docs request process. (format, tools, etc.)

These conversations unearthed an array of needs. Some points had unanimous consensus:

• Since the entire organization used Slack, a desire for this process be integrated with Slack – potentially even a way to submit requests via Slack – was wanted.
• All teams wanted a way to track updates to their requests, especially to be notified when one was completed.

However, there were some conflicting requests, including:

• Some wanted a process that would also be open to customers, so that customers could file requests themselves. Others wanted to keep this process internal and have customer requests filtered through teams like Support and Success.
• Different teams used different project management tools (ex. Asana, Trello, and/or Jira). Each team stated their preference for a process that aligned with their tool, ex. a new request would turn into a task in Asana, a card in Trello, or a ticket in Jira.

I addressed these conflicts in the outcome section. Spoiler alert: I wound up selecting Jira, and kept the docs request process limited to employees only (for now). 

Based on all this feedback, I outlined a process in which the requester could do the following:

• Submit docs requests which would include their identifier (name or email), a requested time frame to complete it by (ex. two weeks), and all relevant details (a description field).
• Automatically track requests they have submitted, and be able to edit after submission if they realized they left out a detail.
• Share requests with relevant team members so they can track and add notes to the request.
• Be notified when the request is complete so they can follow up with customers or team members.

Evaluating Tools

With this information, I outlined what I needed out of a docs request process to support each team. 

At that time, I was completing docs requests informally via Slack and email. To figure out the best way to prioritize incoming requests, I reviewed the ones I’d already gotten and brainstormed ways they could be prioritized.

• By date of submission
• By (requested) date of completion
• By request type (Installation, Integrations, etc.)
• By estimated time to complete
• By requester or team

Writing these out helped me come up with a strategy for types of categories, tags, and metrics to organize and prioritize incoming docs requests. 

To select my project management tool, I demoed a few options:

• An Asana board with requests on a board organized by window of completion (ex. two weeks)
• A Trello board with cards for requests tagged by request type (ex. support)
• A Jira Kanban board with requests organized by status (backlog, in-progress, complete)

After these trials, I ultimately decided to go with Jira, which offered several important features that have been integral to the success of my docs request process: 

• The requester and assignee roles are automatically updated, which supports me to scale the docs request process to include more than one docs writer.
• The ability for other team members to ‘watch’ a request that is important to them (ex. an engineer can watch a request related to a feature they’re building).
• Support for threaded comments for in case there is extended discussion on a request, which comes in handy pretty often.
• Already used by the core teams I work most closely with (Support, Product, Engineering) so it can be seamlessly integrated into their workflows.

Drawing The Rest of the Owl

With the tool selected, I set about bringing the process to life. To provide a lightweight structure for requesters, I created a simple five-question form they could fill out. 

Question #1: Topic(s)

For metrics and prioritization, I ask them to indicate the topic(s) of the ticket (you can select more than one).

Question #2: Completion Window

For product releases, since the exact release date usually wasn’t solidified until a few days out, the window of time options provided the flexibility to meet their needs. 

Question #3: Request Summary

To help them structure the Jira ticket as they wanted, I referenced the parts of the form that correspond to which parts of the eventual ticket. 

Question #4: Request Description

The “provide context” part was added later on based on a particularly painful experience where I was forwarded a Salesforce case that was 100+ messages deep by the time I got to it 😬.

There’s also an optional question below this one where you can attach up to 5 files (ex. screenshots) related to this request.

Question #5 (Docs Team Only): Story Point Value

This question was added after we expanded the docs team and established a process for quantifying our workload. We use the fibonacci sequence to estimate the complexity and amount of time it will take us to complete the ticket. A quick summary of these numbers and how we use them:

• 1 point: A request with no complexity; takes less than 1 hour to complete (ex. screenshot updates)
• 2 points: A request with minor complexity; takes 2-3 hours to complete (ex. a rewrite of an FAQ)
• 3 points: A request with mild-to-moderate complexity; takes 1-2 days (ex. a rewrite of a guide)
• 5 points: A request with high complexity; takes 3-5 days (ex. a rewrite of 2-3 guides)
• 8 points: A request with very high complexity; takes 1+ week (ex. a rewrite of an entire section)

(Blog post on how and why we adopted this system coming soon!)

Workflow Automation (Jira <> Zapier <> Slack)

Next, I used Zapier (a workflow automation tool) to trigger two actions once the form was completed:

1. Create a new Jira ticket in the backlog board of my DOCS project in Jira.
2. Post a message to #cs-support-docs announcing the new request.

The Slack post was especially helpful for Support as new customer write-ins came in that were related to the same doc request.

As of today, requests coming through that channel are structured like this. I’m in the habit of emoji-reacting to let people know that I have acknowledged or completed the request.

Last but not least, here’s the Kanban Jira project that we use to manage these requests. 

Here’s what an individual ticket looks like. To track completion metrics, I use tags for:

• Priority level
• Whether it’s a request for a new or update to an existing doc
• Whether it’s a request for Help Center or developer/API doc content

Outcome

The docs request process was unanimously well-received by the teams I work with, and was brought up multiple times as a highlight during my very first performance review. 

I also closed the loop on certain “agree to disagree” key decisions:

• I followed up with the teams who wanted me to use Asana and Trello about my decision to use Jira – they understood my need to align with Product and Engineering.
• I let customer-facing teams know why I chose to not allow customers to directly submit docs requests – they understood and agreed to submit these requests on their customers’ behalf, since they usually have additional context for those requests that made them easier to act on.

Though it took a few friendly reminders, the team quickly adopted the process. It continues to be the de-facto docs request process for all Heaple, 5+ years and 2 acquisitions later (hence the ticket screenshotted above being ticket number 1424!).

Additional Workflows

During my time at Heap, I enjoyed challenging myself to automate as many workflows as I could, mainly using Zapier and Slack. Here are a few of the ones that the team found most useful.

Suggested Edit Notifications

Suggested edits is a custom feaure that we added to our Help Center to allow team members to submit Wikipedia-style revisions to docs. This made it easier for those team members to collaborate with us on fixes where they knew exactly what needed to be changed, such as updating a version number or removing an outdated sentence.

Once this feature was launched, I wanted to make sure we could act on these revisions as soon as they were submitted. To support this, I used Zapier to forward the email notifications generated by a new revision request to a dedicated Slack channel.

Here’s the Zap action:

Here’s what the submitted revisions looks like in Slack:

The link allowed us to jump directly to the request so we could review and approve it. We loved providing a quick turnaround time for teams that made our jobs easier by directly suggesting edits, and this workflow allowed us to do just that.

The only road bump we ran into with this workflow was that Gmail occasionally marked these emails as spam, so we set up email filters to prevent that.

Customer Feedback Submissions

Customers can leave feedback on any doc by clicking the 👍 or 👎 icon and entering their email address and a comment.

To make sure we always saw (and acted upon) these comments, I leveraged Nice Reply’s integration with Slack to send these to a dedicated Slack channel for customer feedback.

These posts came through with all the info we needed to follow up – most of the time, we would file a ticket, though occasionally, we’d reach out to the customer (or their CSM) to learn more about their request.

Our customer-facing teams especially appreciated this channel for spotting feedback that came from accounts they were working with.

Docs Platform Status/Outage Alerts

One of the most stressful things that can happen to a docs writer when there’s an outage in their documentation hub 😱. Since our two docs sites lived on two different platforms, we wanted to know immediately if there was ever an outage with one.

Since neither CMS had an integration with their status page and Slack, I signed up for email alerts about status changes, then set up a Zap to send those email alerts to a dedicated Slack channel.

The email came through with a summary of the issue along with a link to the status page.

Later on, we were able to leverage our Engineering team’s use of PagerDuty to escalate outages, so these alerts came through from there instead.

Recent Updates to Docs

A type of automation that was highly requested by team members who lean heavily on docs was a way to be alerted anytime any of our docs was updated.

Since it wasn’t possible to set this up in a way that distinguished between bigger vs. smaller edits (ex. correcting a typo) I knew this was going to be a very noisy feed. I opted to have it in a dedicated Slack channel that folks could opt into if they want to keep up to date on all the updates.

Here’s the Zap action:

Here’s what the update notification looks like in Slack:

I wish I could have the Slack post to say WHO made the edit – unfortunately, that functionality doesn’t exist at this time. When it came up, we encouraged folks to check the doc revision history.