Part 3 of our Developer Experience Series.
Developer Journey reviews, and friction audits are one of our top consulting offerings. For these, we don our developer hats to review websites, resources, and products, just like prospective developers would, with the ultimate goal of creating a "hello world" proof of concept. Then, a detailed friction log is provided outlining the good, the bad, and the ugly things experienced, with recommendations on how to achieve a better journey and experience for your developers.
A key tool we use is our Developer Journey map, which is quickly becoming the de facto standard framework amongst DevRel practitioners.
Below is an example of a developer's journey that was tracked using the map, one which had a high amount of friction.
The six points of friction we see most often are:
Poor technical documentation
Lack of a developer portal
Lack of an official forum or community space
Mandatory commitments (e.g., Entering contact information) to access resources
Lack of GitHub repo descriptions
Insufficient trial periods.
Read on to learn why these make the Developer Journey difficult, and what you can do about them.
1. Poor Technical Documentation
Technical documentation is the number one resource developers need in their journey, but most fall short in the following areas:
Lack of an Overview: Often, the developer is led straight into the technical details without having been provided sufficient context. The first topic should explain what the solution is and what problem it solves.
Lack of a Quickstart: Next, a Quickstart should be available to guide the developer from scratch to a working hello world example, but this is usually lacking or missing.
Identification of hello world: Many companies haven't created a good hello world, which makes it hard to produce a Quickstart.
Lack of tutorials: The Quickstart should be complemented with tutorials showing how to accomplish specific tasks. If they're missing or intermixed with reference guide materials, this can create confusion for the developer, and a messy content structure.
API docs using auto-generated tools: There is a common misconception that creating API documentation from code comments means developers are more likely to write and maintain it. In practice, the opposite is true, and the formatting from auto-generation documentation tools is generally atrocious. See our blog: Why I Never met an Auto-Generated Doc I liked, for more information.
Why it causes friction:
If developers can't figure out how your product works or how to build a proof of concept using your documentation, they will likely end their journey early. Even if they can cobble something together, bad documentation hints at the friction they'll continue to encounter moving forward with your product.
What to do about it:
Design a good table of contents as your content architecture. Typically the top level of your table of contents should be organized like this:
Overview
Getting Started
Quickstart
Tutorials
Reference Guides
API Reference (may be in a separate part of your documentation system)
Support (including FAQs)
As part of this, identify a good 'hello world' for the Quickstart, and several good tutorials that showcase general use cases. Ensure the reader has all of the resources they need to follow the tutorials, including a free trial, sandbox, security key(s), access to the APIs, etc. And ditch auto-generated documentation for a modern system like readme.com, which all developers can contribute to thanks to its visual, online UI and underlying markdown syntax.
2. Lack of a Developer Portal
Signposting developers to technical resources is critical to ensure they can find the information they need. But all too often, links to technical resources are treated like an afterthought and buried amongst marketing fluff. Developers hate marketing fluff.
Why it causes friction:
Resources like use cases, white papers, technical documentation, and code samples are top of developers' minds, especially when they're accustomed to high-quality developer portals from companies like Microsoft. Fail here, and developers will likely leave the journey early.
What to do about it:
Creating a developer portal shows developers they are important and guides them on their journey. Start small by adding a Developer menu at the top of your website to signpost developers to technical resources, and then evolve it into a dedicated developer portal.
3. Lack of an Official Forum/Community Space
Developers rely on communities to get technical help, share information, and learn what others are doing with your product. Community sites, whether external ones like Stack Overflow, or your internal forums, are invaluable for finding solutions to specific problems. Furthermore, contributions from community members can help reduce the load on your Support department. During their Discovery and Evaluation phases of the journey, developers will evaluate these resources.
Why it causes friction:
Developers want to know that support is available, accessible, and active. If your product doesn't have a community behind it, it may reflect poorly on your product, and your Support department may become overwhelmed as your customer base grows.
Just as bad is having an official forum you don't participate in (e.g., due to lack of budget for product support). Questions that go unanswered leave a bad impression and developers may look for better supported solutions.
What to do about it:
Create an official forum with tools like Discord, Slack, or Stack Overflow. Allocate resources from your teams to monitor and answer questions on those forums and to show you're interested in your developers' success. You may need to secure budget from upper management for this, so prepare to explain why your organization's success depends on your developers' success.
4. Requiring Contact Information to Access Resources
Developers rely on the resources you provide to evaluate your product. Unfortunately, many organizations enforce various commitments for access (e.g., email address, service sign-up, credit card details, etc.).
Why it causes friction:
During the Developer Journey, the developer is likely not ready to commit yet – they're trying to get information to make an informed decision about your solution.
Attaining contact information or a sign-up too early may work for traditional marketing, but it's generally unwelcome in the Developer Journey.
If developers can't easily access important resources early, without commitments, they'll miss information that could've helped them move forward with your product.
What to do about it:
Be transparent and provide full access to information from the start. If you must collect an email address, allow immediate access to the resource even if an invalid email is provided. Similarly, ensure your free trial account tier doesn't require payment information.
Have faith that a developer who can get themselves through the Developer Journey is more effective than pushing them through the 'ol sales funnel.
5. GitHub Repo Lacks Descriptions
GitHub is popular for hosting resources like code samples, APIs, libraries, etc. However, without careful thought, a repo can quickly turn into a dumping ground from past coding sessions. Telltale signs include poorly-written readme.md files, out-of-date source files and samples, and cryptic project names.
Why it causes friction:
Developers are keen to see a rich set of resources on GitHub that are up-to-date and documented. Failure here means developers could lose confidence in what should be a valuable resource. And if developers can't rely on them later in the Developer Journey (e.g., to build a hello world POC) they may look at your competitors' offerings instead.
What to do about it:
Keep your GitHub site maintained and up-to-date. Ensure its root readme.md has your company logo and an overview of what's available (like Microsoft does). Include a table of contents linked to each project and a brief summary of each. Then, ensure that each project repo has a quality overview explaining what problem it solves, the directory structure, important files, and how to get started.
6. Insufficient Trial Period
A trial period allows developers to test your product and build their hello world POC. Unfortunately, many trial periods are too short and/or the trial's service tier is insufficient for evaluation.
Why it causes friction:
Developers are busy and may be evaluating your solution amongst those from competitors over several weeks. If the trial period is too short (e.g., only a week or two) or they can't do everything promised in the trial, they may not complete their journey and full evaluation.
What to do about it:
Provide an adequate amount of trial time. A good rule of thumb is 30 days, with the flexibility to prolong it should a developer request additional evaluation time.
Be sure the developer can do everything your website promises in the free trial. They won't be pleased if they need to upgrade to a higher paid tier to complete their evaluation. If certain features are not accessible in the trial, clearly state that upfront to manage expectations.
Finally, provide top-notch support during the trial, even though the developer isn't a paying customer yet. It’s an opportunity to show that you care about the developer's success with your product and how great your Support personnel are.
Make your Developer Journey Frictionless!
Reach out if you’d like our developers to review your Developer Journey and provide you with recommendations for a frictionless experience.
Don't miss new posts. Get email notifications by subscribing to our blog.