For a developer service that has an integration starter or template, you often need some form of prerequisite before the experience can be fully "connected" like a database connection or API auth token.
The default experience would be the template not working or throwing an error without this information. The expectation is simply RTFR – read the effin' README.
Except many people don't read the docs (as much as we'd like them to).
This leads to them booting up the template and immediately running into an error due to a prerequisite. This creates a barrier to entry (and a bad impression), even if it seems like overcoming that barrier is small (it's not, for someone brand new to your tool where this is their first encounter). It's easy to dismiss this as a problem between the chair and the keyboard but it has side effects.
If you're developing tutorials or how-to's that use the template, you now need to cover this in videos (there's no "happy path"), adding call-outs in READMEs ("Be sure to add
API_KEY"), adding warnings no one reads to the docs, etc.
A better way to think about this is to view the template itself as an onboarding experience – help developers set themselves up for success. After cloning and running, can the template itself help a developer set it up?
This not only reduces the amount of how-to in the docs, it leads to a faster Hello World experience.
Here's an example...
I'm building out 3-4 "cloud starter kits" right now and it requires some setup in the templates – however, there is a demo instance of the product anyone can connect to so I actually updated the templates to use that as a default experience. The templates then show a "welcome screen" with set up info and match the aesthetics of the SaaS experience (same branding, colors, design tokens, etc.).
This makes the how-to video and walkthroughs more striking and visually pleasing – they're now "on brand" which is a bonus for improving first-time impressions.
Better yet for onboarding DX – it reduced the TTHW for deploying to one cloud vendor by 64% by cutting out extra configuration steps out-of-the-box.
Have a lovely day,