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.
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.
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
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.
Get more DX Content!
Every two weeks, we'll release a new guide to a different part of DX. Sign up, and we'll email you when we release new Developer Experience guides!
We'll email you very infrequently, and it'll always be about high-quality DX content!