Developer Documentation Best Practices

Proprietary and Confidential ©2021 OpenView Advisors, LLC. All Rights Reserved 1
Developer Documentation
Best Practices
Sam Richard - OpenView Growth Team

Challenges:
• Developer-focused tools can greatly improve organic discovery and conversion by
ensuring that their documentation acts as a side-door to the product.
• Often, developer documentation is so product and feature focused that it doesn’t
answer the question ”What’s in it for me with this product?”
What OpenView did:
• We researched 20+ developer-focused products’ documentation using the internet
archive to understand trends and best practices used by top companies in the
space.
• It’s important to note that this is a follow on to our Developer Buyer Journey, and we
recommend reviewing that first.
Research background

Messaging
• Prospects come to each product with a "mental checklist" to complete before getting started
Direction
• Direction is every part of the journey that gets a buyer to the point where they find value in the product
• This includes the website, signup flow, documentation, and value discovery paths like guides and test data
Value
• This is the ‘aha’ moment for a user of the product, where they perceive value in the software
• This moment of value could vary by persona
Human
Touchpoints
• Human Touchpoints are the deployment of sales and support resources to move buyers along their journey
Recall: What do developer audiences
need?
Documentation helps in the green boxes

How does documentation help?
UI
User Interfaces can also be
helpful help new visitors
navigate getting started
and experienced users can
search for what they need.
A strong User Interface can
help direct visitors to
understand your offering if
you have multiple products.
Messaging
Businesses shy away from
“sales-y” language, but
you should still inform your
audience why each feature
is beneficial to them.
Discoverability
Using an internal wiki might
help with credibility, but if
it’s not discoverable on the
web, it’s never going to be
a channel that grows your
user base.

5
Proprietary and Confidential ©2021 OpenView Advisors, LLC. All Rights Reserved
User Interface
Leveraging layout to give
developers direction

“The documentation seems straightforward, so I trusted it, but it
didn’t tell me steps to take after the first one.”
“Now that I’ve shipped data to the product, ingesting it is in a totally
separate part of the application and there’s no instructions on how
to get there.”
Potential buyers
ran into many
hurdles on where
to find things, or
where to go next.
Recall: once in the application, participants
often didn’t know what actions to take
“I was expecting a self-serve module that allowed me to take action but
ended up at what feels like a dynamic API document. That was
unexpected. I need more explanation.”
Adding Data to
Product
Guide the user through product set up via documentation the same as if you used in-app cues in a
product. This includes highlighting your activation points, and clarifying which parts of the product
are free, which are commercialized, and where users can find the most value.
How Documentation can help:
Documentation

Great Example: Stripe
Stripe capitalizes on SEO
(discoverability) and helps users
route to exactly what they want to
get out of the product with these
common use cases highlighted
outside of the left-hand navigation
bar.
Known Customer Journeys
Single Call to Action
Stripe forcefully guides developers
to learn about how to get started
with their documentation landing
page. This helps keep the message
and understanding of the product
uniform.

Great Example: Snyk
In 2017, Snyk differentiated by organizing docs with
clickable images. Now, the navigation is welcoming to
newcomers with strong calls-to-action to learn how to
get started.
2017 2021

9
Messaging
Continuously driving home the
value of your product.

Checklist Item Description
Solves Need
Users weren’t willing to try a tool out unless it make their “top 3 list”
based on the website description.
Social Proof
50% of prospects wanted to see what other companies used the tools
we interviewed them about.
Integrations
The developer stack is huge and interconnected. Prospects want to be
sure your tool can fit in.
Pricing Buyers at smaller orgs wanted to see a pricing page.
Recall: Developers come to a product
with a mental “checklist” before trying
This is why messaging is key in docs, too

Great Example: DataBricks
DataBricks highlights more commercial
language with blue boxes throughout their
documentation.
This color coding is helpful because it allows
developers who are familiar with the
offering to simply skip over it once they’ve
seen it.

I particularly like how direct
the team’s language is in the
first sentence of this chapter
of documentation.
They have a feature + how
you can add onto it later.
The one thing I’d add for
the Cypress team to make
this page even stronger
would be to elaborate on
why recording tests is
helpful.
Great Example: Cypress.io

13
Discoverability
Many users discover products
through direct links to their
documentation.

Using Google Analytics:
If there are no “landing pages” on your docs URL, you
may not be discoverable.
If you’re hosting your docs elsewhere, address
discoverability with your provider.
Make sure they’re not using code to block crawlers.
How will you know if your
documentation is discoverable?

15
Takeaways

How does documentation help?
UI
User Interfaces can also be
helpful help new visitors
navigate getting started
and experienced users can
search for what they need.
A strong User Interface can
help direct visitors to
understand your offering if
you have multiple products.
Messaging
Businesses shy away from
“sales-y” language, but
you should still inform your
audience why each feature
is beneficial to them.
Discoverability
Using an internal wiki might
help with credibility, but if
it’s not discoverable on the
web, it’s never going to be
a channel that grows your
user base.

About the author
Director, Growth
sam@ov.vc
Sam Richard focuses on the customer’s journey to value in
freemium and free trail software offerings with a special
interest in Open-Source, Developer-Focused, and Security
tools.
In her work at OpenView, Sam conducts teardowns of free
offerings for prospects and portfolio companies,
interviewing dozens of developers about their tool and
purchasing preferences.
If you have questions or comments about the piece, please
reach out via email or on LinkedIn!
Sam Richard

18
Thank You!
Sam Richard - sam@ov.vc

Developer Documentation Best Practices

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à Developer Documentation Best Practices

Similaire à Developer Documentation Best Practices (20)

Plus de OpenView

Plus de OpenView (20)

Dernier

Dernier (20)

Developer Documentation Best Practices