Crafting the Perfect 'Getting Started' Guide: A Five-Step Blueprint for DevRels
Writing an effective developer tooling quickstart is surprisingly difficult!
A ‘Getting Started’ guide serves as a gateway for users to explore and get comfortable with your product. It can also be a fantastic user acquisition funnel (especially if you’ve adopted PLG) and a way to grow your community! However, creating an effective guide is an art that balances between providing essential information and maintaining simplicity.
In this post, I unravel the top five crucial steps to craft a guide that empowers engineers to use your product easily and confidently.
I’ve written my fair share of developer tooling “getting started” and “quickstart” guides over the years, some of which are still visible on the interwebs:
Let’s explore several best practices and goals I kept in mind while working with my teams to create these guides.
Understand Your Audience
Target Audience Identification: Defining your ideal customer profile and core user persona is essential (and don’t worry about the buyer persona so much at this stage). Understanding the skill level and expectations of your audience is also paramount. Tailor your guide to suit experienced professionals or beginners as needed.
User Needs Assessment: Delve into what users aim to achieve with your tool. This is all about the “jobs to be done”! It sounds obvious, but addressing their primary needs in your guide paves the way for a satisfying user experience.
Plan Your Guide
Create an Outline: Draft an outline encapsulating the core sections, such as introduction, installation, and basic functionalities. This acts as a roadmap, ensuring you cover all essential bases.
Prioritize Information: Present information in a logical sequence, from installation to advanced features. This is especially important for engineering folks, as many of us identify as being “logical beings”, and it helps to make the learning curve gentle for the users.
Create an Engaging Introduction
Concise Description: Kickstart with a brief yet engaging description of the problem you are solving and what the reader can expect to learn upon completing the guide. You can also include a brief pitch about your tool and its value proposition.
Illustrate Use Cases: Highlighting a few practical use cases can ignite interest and provide clarity on what can be achieved with your tool.
Illustrate Basic Functionality
Step-by-Step Tutorials: Offer step-by-step tutorials for common tasks, ensuring users can quickly grasp the basics. Show, rather than tell, and be sure to include the outputs of commands run of actions done, as this helps someone scanning the page understand what they will achieve.
Visual Aids: Incorporate screenshots, diagrams, or videos to visually explain concepts, making the learning process more engaging and easier to follow. This sounds obvious, but I’ve seen far too many docs sites that were simply a wall of text with the occasional code snippet.
Provide Support and Additional Resources
Troubleshooting Section: Include a section dedicated to solving common issues or errors (even if your tool isn’t at fault). This empowers users to find quick solutions and not abandon the getting started guide at the first sign of trouble.
Links to Further Resources: Link to in-depth documentation, forums, and support channels for users seeking additional help or advanced learning.
Bonus Step: Test, Test, Test, Instrument, Instrument, Instrument…
Ideally, you want to test any getting started guide with a subset of your core audience before rolling this out. Using your engineering team might help, but be sure to ask yourself if they represent your core customer (often they don’t!) You can also pay to have people review the guides by tapping into your community or champions or using professional beta testing services.
Regardless of whether you beta test document, you should always instrument your getting started guide. The goal is to understand where readers got stuck, clicked the wrong thing, or abandoned the guide. At a minimum, you need something like Google Analytics. Ideally, you’ll use a behaviour analytics tool like Hotjar, or create custom events that fire off into your CMS when readers complete activities.
Regularly review this qualitative and quantitative feedback, create new hypotheses, and run new experiments. I’ve seen some stunning turnarounds in user happiness, tool adoption, and sales conversion by improving a getting started guide.
If you’re working in a product-led growth (PLG) developer tooling company, a getting-started guide may be your single biggest lever to drive adoption. Ben Williams has shared a lot of great advice from his time at Snyk on how to run experiments and be data-driven in his The Product-Led Geek newsletter.
Wrapping Up
Creating a 'Getting Started' guide is not just about writing a series of instructions; it’s also about crafting a user’s journey towards becoming proficient with your tool.
By understanding your audience, planning meticulously, crafting an engaging introduction, elucidating basic functionalities with visuals, and providing ample support resources, you pave a smooth path for users to traverse from novices to (almost) expert users.
Please comment below and let me know if you want more content on documentation or writing getting started guides.
And don’t forget to subscribe! I’m aiming to share a post every two weeks or so.