Ditching highlighting leads to more concise snippets, more thought to be put to find a minimal example and better overall flow in your writing. syntax Writing content is hard, picking a nice syntax highlighting theme is harder. technical 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 or other hosted solution gist.github.com 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 have highlighted code blocks. not 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 for the 10th time. carbon.now.sh 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 and text in moderation, From there on it’s just a race to the biggest, flashiest text. That’s not something you want to turn your post into. bold italic if a whole sentence or paragraph is bold, it’s hard to anything inside it. highlight 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 is compared to . var 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.

Flow

Twitter

Too Long; Didn't Read

Making security fun one episode at a time

Ditch syntax highlighting for better technical writing

Too Long; Didn't Read

Company Mentioned

Coin Mentioned

Hugo Di Francesco

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

Ditch syntax highlighting for better technical writing

Too Long; Didn't Read

Company Mentioned

Coin Mentioned

Hugo Di Francesco

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES