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.
2. Difficult to further highlight inside something that's highlighted
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.
Top comments (0)