Project: Revamping Developer Portal
Tatiana Perry
Presentation Designer
Technical Writer
Content Research
Project Summary
Current Issues - Internal
There is no process around documentation
Readme is limited in site organization
Content management is difficult
Support doesn't feel enabled to write documentation
Support has a lot of tickets that are solved by directing to them existing information
SEO in Readme is not working correctly
It’s difficult to add new content types
Current Issues - External
The site is hard to navigate and information is difficult to find
Getting started has a high barrier of entry
Most content is in the API reference
SDKs are poorly documented
Site search is not obvious
Changeling/Release notes are hard to find
It’s difficult to add new content types
Content issues
There is no style guide
We need more use cases to help people with integrating
More automation
Rewrite high touch point topics
Proposed Improvements
Content Management
Site Design
Content
The developer portal audit and project summary were part of a project that required a full-revamp of a developer portal. The project was completed on time and on-budget. Client information has been redacted.
Project Summary
Currently, the documentation is not serving our developers or our support team. We need to create documentation that delights our developers, make it easy for new developers to start building and makes it easy for anyone at Company A to author content.
Once complete the developer documentation should have:
Customer sign in
Interactive tutorials
Easy authoring experience
Use data from multiple repos
Current Issues - Internal
An internal user is defined as a user that is employed by Company A.
There is no process around documentation
There is no process to create, edit, or remove documentation. Currently a “free for all”. Content doesn't follow a style guide. Leads to confusion and inconsistencies in the documentation.
Readme is limited in site organization
We have a lot of content. Readme forces all content to top level page, so users who navigate using the page have to scroll to see some content.
Content management is difficult
There are few user controls such as editor, viewer, and admin. The API documentation is difficult to keep up to date due to confusion interface and no GitHub integration.
Support doesn't feel enabled to write documentation
Support wants to contribute more to customer documentation but does not have the ability or know how to contribute.
Support has a lot of tickets that are solved by directing to them existing information
There are a lot tickets that are solved by attaching a link to a ticket. Customers can't find the information they need.
SEO in Readme is not working correctly
Metadata descriptions can't be controlled. They are generated by Readme using the first of a document. Section descriptions are controlled by the project settings. So top level pages such as /docs or /community have the same meta description.
It’s difficult to add new content types
Unable to add GraphQL content since it's not supported by platform.
Current Issues - External
An external user is defined as anyone that is not employed by Company A and uses the documentation.
The site is hard to navigate and information is difficult to find
The current setup doesn’t match their mental model. Based on user research and interviews with customer success managers, the user path in the documentation doesn't match how teams are directing customers to set up the app. Users must navigate a site that has a very long navigation and search that doesn't return the information they expect.
Getting started has a high barrier of entry
Users must sign up for other services such as Google Console or Azure. Then come back to our to finish set up.
Most content is in the API reference
The content is not searchable here due to platform. Since there is so much content there, reading the reference takes too much time. Can be hard for users who want to take deep dives and for those who want to do quick lookups.
SDKs are poorly documented
The SDK documentation is not automated. Since they require manual updates, updates often get missed.
Site search is not obvious
Site design makes search hard to find.
Changeling/Release notes are hard to find
Site design makes the release notes hard to find. There are no page notifications or customer emails about product changes.
It’s difficult to add new content types
Unable to add GraphQL content since it's not supported by platform.
Content issues
There is no style guide
Each page is written differently. There are no templates for writing content.
We need more use cases to help people with integrating
Integrating is a complicated process. There isn't any guidance on how to accomplish this with the 3rd party apps customers are using.
More automation
Create automation around:
Style guide
API documentation
SDK documentation
Rewrite high touch point topics
Authentication, webhooks, and best practices are the top support tickets. Content has not been updated around these topics in over a year.
Proposed Improvements
We need to focus on three main areas.
Content Management
Move the content into a standard format like Markdown.
Implement a docs-as-code workflow where changes are reviewed before publishing.
Move to a platform that support multiple content types.
Perform automated checks against the API and style guide.
Establish a procedure for getting documentation published and make it easy for anyone to contribute content.
Move the REST API reference to OpenAPI for easier management and keeping with industry standards.
Create a style guide with branding team.
Site Design
To increase developer engagement and ease of use we should:
Highlight tutorials.
Highlight existing developer tools.
Landing pages to bring focus to certain products and features
Add interactive tutorials to reduce “Time to hello world”.
Make search easier to find.
Align documentation to product segmentation.
Create an interactive API reference.
Design site to match existing products.
Content
Work on clearing out backlog.
Work with support to identify gaps.
Move towards having documentation for more advanced users.
Reorganize documentation based on feedback from support, product alignment and analytics.
Provide links betweens related docs.
Split existing documentation in smaller easier to digest sections.
Group similar topics.
Remove extra pages forced by Readme - landing pages that don’t add to reader understanding and are just another navigational step.
Make sure content follows the style guide.