Matthew Revell - By the time they're reading the docs, it's already too late

This talk was presented at API The Docs Virtual 2023 Feedback, Metrics and Analytics event series on 22 February. We are glad to present the video recording, slide deck, talk summary, and the panel discussion below. Enjoy!

Visit the talk listing page for an overview of all presentations!

Matthew Revell

Founder and CEO at Hoopy

Expanding of what we know as Documentation

• People have prior knowledge, opinions, questions and maybe misconceptions about documentation.
• To guide them, you need to step into the developer journey process before the sign-up happens.

Documentation is just one stop on a bigger journey

DX documentation focuses on SDKs, reference docs, Swagger files, etc.

Make sure that the users:

• understand your terminology,
• take into consideration your solutions to their problems,
• are comfortable with your role in this process, and what you do.

Customers often build their devportals leaving out the prior steps in the process. Leaving them out, and jumping into technical details is off-putting.

Tree vs. forest situation

• Look at the developer journey as a holistic experience.
• Try to understand what each “tree” represents in the “DX forest”.
• It’s easy to miss the “forest” because of the “tree” in this case, too.

Developer Journey Map [from Developer Relations book by Caroline Lewko, James Parton]:

• Discovery: the user wants to know about your product, what it does, and can they trust you.
• Evaluation: the user receives proofs of concept, and engages with your documentation.
• Learn: the user works with your documentation and product, engages with the community, and questions their own confidence.
• Build: the user’s first MVP build, thoughts about their experience with the product: is it valuable for them?

• Scale: the long term plans of the user with product, giving feedback and contributions. Trying to ”grow” with the product

• Not all of these types are necessarily in devportals.

• From the holistic approach, everything that has technical content is a form of documentation.
• Documentation covers all five stages of the developer journey.

Take a step back: where does the developer journey start?

• Developer journey begins when someone doesn’t know that they have a problem.
• Then they look for available solutions.
• Start producing your documentation early to meet the needs of these people.
• Shape people’s perception of their problem, to favor your solution. In other words, educate them.

Measuring documentation

• No one reads a documentation ”cold” (taxonomy, language and assumptions are not introduced).
• Inform the developers about your documentation in time.
• They will try other solutions and form opinions before coming to you.
• It will shape how they interact with you and your product.

How do developers evaluate tech?

• Use Google to discover the landscape of the market.
• Talk to peers.
• Check the community around a technology.

• Evaluate the documentation regarding the solutions.

• Developers form an opinion while evaluating their options.

• Influence them during this time, so they connect with your product easier.

Marketing, education, docs and community are part of this same plan

The Devrel continuum: the things we do to relate to developers are all part of the same system:

• pre-signup: building awareness, reaching out and trying to change opinions
• developer docs: tutorials, guides, quick-starts

• post-signup: presenting proofs of concept, active support, events, achievements

• Establish in people’s mind how you are going to teach them about your product.

Summary

1. Docs do not stand in isolation, they are part of the devrel continuum.
2. The sooner you establish yourself, the sooner you will start educating people and bringing in new customers.
3. Docs do not start and end on your devportal.
4. Coordinate across teams to deliver coherent developer experience.
5. Just begin sooner.

At this event, the presentations were followed by a panel discussion, where the speakers shared further thoughts and insights.

Panel discussion

Participants: James Noes, Matthew Revell, Laura Vass.