Ditch syntax highlighting for better technical writing

Ditching syntax highlighting leads to more concise snippets, more thought to be put to find a minimal example and better overall flow in your writing.

Writing technical content is hard, picking a nice syntax highlighting theme is harder.

There are so many options and each platform has a ton more you can for example:

• export your code as images with services like carbon.now.sh,
• take screenshots of your code in your editor
• use GitHub gists gist.github.com or other hosted solution
• compile your examples to code blocks (eg. as part of your markdown compilation) and leverage CSS or JavaScript libraries to highlight them on the web

The other option is to just not have highlighted code blocks.

Here are a couple of reasons to ditch syntax highlighting.

1. Focus

Focus on the content not presentation.

Spend time polishing and rethinking your examples, not going back and exporting that code snippet on carbon.now.sh for the 10th time.

The code snippets are an intrisic part of your content, not just a nice flourish. Your examples illustrate your points. You don’t edit your content in 5 different formats, your code should be no different.

Make your content pretty but not at the expense of your ability to publish it fast.

Just like you can use bold and italic text in moderation, if a whole sentence or paragraph is bold, it’s hard to highlight anything inside it. From there on it’s just a race to the biggest, flashiest text. That’s not something you want to turn your post into.

What that means is that having large chunks of highlighted code might make it hard for you to show your readers what you’re trying to show them.

3. Content that lasts

Using images or 3rd party services to host your code means your post now needs multiple services to be up for it to keep existing in full.

Services shut down (sometimes quite quickly), images get lost. Don’t let your post live on borrowed time, let it host all its own content.

4. Accessible and fast

Put yourself in the reader’s shoes.

How many times did you load a post on a flaky network, just before the connection dropped, the post flashes, it looks like it loaded, maybe you beat the flaky network this time?

Wrong! The post loaded alright, but to have any of the code, you need the images and the embeds… great.

A code block is just text, it can be interpreted better than an image. Even if that image has a nice alt text and good metadata.

5. Find a minimal case

Not having nice-looking code means you’ll shorten your examples and that’s a good thing.

More explanation, less shoving code in people’s faces. After all that’s why they’re here. If they wanted to read code, they would have gone some open source project’s GitHub page.

6. Write as you speak

Large code snippets, just like massive paragraphs, can start to look like a wall of text.

When you start to mix between small snippets and code inset in your text, the content will flow better. It will be more like a conversation, you explaining to a co-worker or a little sister, what exactly it is that var is compared to let.

A well-written post with inset code is just like a well-punctuated and structured post. It feels a lot nicer to read, happy readers, happy writers.

Conclusion

Reduce the amount of time you spend messing around with your code blocks and spend more time thinking about it.

What other hurdles do you have in your technical writing?

Let me know here or on Twitter: @hugo__df.

Originally published at codewithhugo.com on April 25, 2018.