The Perfect Code Snippet

When it comes to documentation, most of us have the same modus operandi. We scroll to the first code snippet and torture it until it works. Why spend 5 minutes reading the docs when we can spend an hour figuring it out ourselves?

That's okay, though! It doesn't mean documentation is a lost cause, but rather that we should put some extra time into code snippets so they convey the most information with the least amount of thinking.

• 1. Focus attention
• 2. Move to the top
• 3. Remove Extra Content
• 4. Add Mouseovers
• 5. Make it run

Focus Attention

Not every line of code is equally relevant… but that doesn't mean we should cut them! There's nothing worse than copying a snippet, and trying to figure out where the heck a variable came form. While including all the context can be a bit overwhelming and cluttered, being able to see the full picture is necessary.

So, keep the content, but highlight the relevant lines! This way, the less-relevant boilerplate setup code is still there… it's simply faded it out so your eye is drawn to the relevant content.

Move to the top

When we write documentation, we tend to like to set the scene properly and get all the information out in the open. But when we're reading it? Our eyes glaze over as we scroll down in search of something we can copy and paste.

Honestly, how many hours of strife would be saved if people just read the documentation instead of jumping into a code snippet? But it’s moot – we can’t change people’s behaviors. However, we can embrace it. In fact, there’s no shame in developers skipping to code snippets. That feeling of "I’ll figure it out" is a huge part of why we became developers. So rather than fighting it, there’s ways to augment our code snippets to deliver the same information without asking people to wade through paragraphs of text first.

A rule of thumb: your first code snippet is where your documentation effectively starts. People like to scroll down, not up. Down feels like progress. Up feels like admitting defeat. The higher up the code snippets on a page, the better, since people often tend to write off everything before the first code snippet as dribble, like the I still remember that summer with my grandmother… preambles that accompany most online cooking recipes these days.

Add Mouseovers

One downside of putting the code snippet at the top is that we don’t get to add context to the code snippet before the user sees it. For example, we don’t get to tell them how to install a certain package, or explain where certain variables come from.

Most developers don’t like to learn in a linear way, though. They like to dig in and figure it out for themselves. By hiding things in the code snippets, we're helping them explore at their own pace rather with information when they need it.

And, best of all, the context is unambigious! It's clear what's being referenced, and the extra details are right in context.

Remove extra content

Since we've put a lot of the content in mouseovers, we can remove it from the text. The less text we have, the more likely someone will actuall read it… and more likely the signal to noise ratio is higher.

Make it run

Imagine you'r

One of the best things you can do for DX is tighten the loop as much as possible. Writing code is always scary, and there's a ton that can go wrong. The

Added bonus! It's amazing how many code snippets don't actually work. By making it run inline, we remove the ambiguity for both the users and ourselves.

The Perfect Onboarding

For many developer tools, the onboarding is the product. As users set things up, they're interfacing with the product directly more than they ever will in the future, and the initial setup can make or break the entire experience. We're going to alk through how to onboard new users into your API the best way possible.

• 1. Set Expectations
• 2. Get Personal
• 3. Show the Code
• 4. Give Feedback It Worked
• 5. Give Next Steps

1. Set Expectations

When someone's getting starting, they have no clue what they're getting themselves into. Will it take minutes or hours? What do they need to prepare? It's never fun to start working on a new API or code library, and find

You also want to be clear what the ultimate goal is. You're asking for a lot of work up front, so the least you can do is make it clear what they can expect once they've done it.

Give them a reason (MVC)

Nobody has ever wanted to just use an API. They had something they wanted to accomplish, and a certain API is the best way to accomplish that. So, don't make the onboarding something generic. Instead, figure out what your API's elevator pitch is, and help people get to that.

Your onboarding should have a real goal, the Minimum Valuable Call. Pick something real that most people using your API will want to do, and help people get started on it. Too many APIs focus on a generic "getting started" guide with no goal.

2. Get Personal

The best documentation is personal! Don't just give people generic instructions on how to get started with ap API — you have so much information about them, and can personalize their onboarding experience a ton. [TODO: redo this whole thing, make it more of a rant on personalized docs!]

There's subtle ways to personalize onboarding in ways that most people won't even notice… but they will notice how smooth it is. We'll personalize this tutorial as best we can, and call it out with a green background when we do!

3. Show the Code

[Text about how important showing code samples is, especially at this part of the journey]

Help with Setup

[insert content about showing how to install npm or a module; b/c of different levels of knowledge]

[maybe something about slack/zapier/etc? "We often assume people at this point want to use our API. But in reality, they just want to do something. Zapier..."]

Tailor it

[insert more bout the personalization, and different signals. "It can come from..."]

4. Give Feedback It Worked

[Content about tightening the loop...]

[Talk about realtime feedback]

5. Give Next Steps

[Add content about giving them somewhere to go next]

[Most APIs have, at most, 5 or so usecases, blah blah blah]. Identify them and give people information on how to do them!

[Talk about reference guide paradox]

Worry-free Error Messages

Errors and their descriptions are essential elements of programming. If everything just worked like we expected it to work, being a programmer would be the easiest job in the world! Alas, a huge part of what goes into any programming role is figuring out why something isn’t working as expected. Developers spend a lot of time deciphering error messages! Here’s how to improve them.

• 1. Unique Error Codes
• 2. Detailed Descriptions with Variables
• 3. Explain the Fix
• 4. Full Context Awareness
• 5. Contact

Unique Error Codes

Do more than send out http status codes, like `Not Found` or `Bad Request`. It is hard to handle specific errors when they fall into generic buckets like this. Instead, create unique codes for each type of error and make everyone’s life a lot easier.

When each code uniquely identifies an error pattern, no additional reference is needed to evaluate an error. Unique error codes add specificity and compactly convey much more information than any limited set.

You want the error code field to be the main check when troubleshooting, rather than forcing users to interpret the error based on the rest of the error message payload.

Since error codes are meant to be referenced by code, they shouldn’t ever change.

Detailed Descriptions with Variables

Be verbose in describing the error, so that the person reading the message has the opportunity to understand exactly what is going on.

Include variable fields! Rather than just saying something like “the version you specified...”, show them what we’re seeing. (such as "the version you specified (v1.0)...").

Here are some examples of variable fields we insert ReadMe API error messages...

Explain the Fix

Most of the time, error messages focus on the problem and leaves it at that. How negative!

Errors dutifully report what went wrong… but they often stop just short of telling us what we actually want to know, which is how to fix the problem!

We recommend a required `suggestion` field to go with every error `message`. While the `message` field answers “what went wrong”, the `suggestion` answers “how to fix it”.

You don’t want users to have to do extra detective work when they hit an error. Be specific wherever possible. For example,

- linking directly to the exact docs page that’s most relevant

- instructing them exactly what to change or take a closer look at on their end.

Full Context Awareness

So you’ve hit an error and are following the link to the docs. You see the standard information about the endpoint you called... and you can see the actual log entry from the specific call that caused your error!

This lets users see exactly what the server sees alongside the endpoints' documentation. From there they can see all details about the error, share easily with support, rerun requests, and more.

Contact