Rocco
Developers typically use quickstarts to familiarize other developers looking at their software for the first time. Quickstarts focus on demonstrating what the software accomplishes and how a developer could use it.
However, more often than not, developers love to make quickstarts with limited information (leading new developers nowhere) or assume developers have everything set up in a particular way and set them up for failure while they follow along. Let’s break down what 'quickstart' should mean for those following along at home:
Sometimes, developers make too many assumptions about an audience, such as having an environment installed or deep prerequisite knowledge of a subject. In that case, you might be setting your audience up for failure.
Quickstarts are in place to get a developer from 0 -> 1 while using your software and show them how it's used in practice. That even could mean scaffolding a few things around it to give a developer a delightful experience.
When thinking about quickstarts, I like to think about it as a recipe:
When building a quickstart, start with a desired outcome, like how we search online for recipes.
When you look online for a chocolate chip cookie recipe and follow it, you want to have a chocolate chip cookie in your hand by the end of it. A good quickstart should have a user go from nothing to a desired, tangible outcome. While building your quickstart, work backwards. For example, if you want a developer to use your authentication library, show them how it can be used in practice with a mock application. Don’t just hand them a library with some vague instructions.
Set a ‘prep time’ and 'baking time' for your quickstart. If your quickstart is called a “quickstart” but takes two hours to follow, you might be in for some rough feedback. Keep it within a reasonable time for any new developer to have their 0 -> 1 moment.
Make sure that this time is tested with a developer who isn’t familiar with your software. You might be biasing your results internally due to existing knowledge of your software; quickstarts are meant for fresh eyes.
If someone's baking something, we can assume that they have at least some of the basics in their home: a fridge, an oven, and maybe a countertop—much like a developer might have an IDE and some knowledge about your domain. However, they might not have the specialized knowledge (‘specific brand’ of chocolate chips) you want them to use.
A good recipe lists all the ingredients and details needed at each step, detailing how each ingredient interacts with something in the kitchen. Good quickstarts list every prerequisite a developer would need and include steps that do not require too many logical jumps. This includes even noting the version of a particular piece of software you’re using in your quickstart (e.g. "Node.js v20.12.2").
Make no assumptions about a developer's environment—you don’t want them to hit a snag at the beginning of following your guide. This also prevents them from hitting environment issues when breaking software versions come out, and you don’t have the time necessary to update your quickstart every time someone else updates their libraries.
Each step should help developers conceptualize where certain pieces of code should go, even if the quickstart allows them to copy and paste code directly. If the task is more involved, you should also show them how their directories should be set up.
Again, get them to where you want them to go, and assume it’s their first time using the software every single time. Your documentation can contain more advanced options and tutorials, but your quickstart is your first impression and hook to give a developer a delightful experience.
Finally, the longer-term goal for any quickstart is to get a developer interested in using your software, much like a recipe is to buying a cookbook or following a specific baker. You want them to go beyond the quickstart and use your software in their applications.
Don't let your quickstart go stale, and routinely ensure that it is working and still providing the same experience—even as your software changes.
Please don't leave them with a bad taste in their mouth.
