Best Practices for Writing on DEV: Formatting

Hey again, Sloan here! 🦥

We’re sharing some tips for success when it comes to writing on DEV. If you’ve been looking to improve your technical writing skills, make the most of DEV as a blogging platform, and take your content to the next level — this series is for you!

The first post in the series was about creating a series. This one is about formatting, and the next two are about tone of voice and topics. Let's get started!

Formatting

Proper formatting is key to ensure that your post is readable, helpful, and polished. Our post editor uses Markdown and Jekyll Front Matter to format posts.

Use of headers

Use headers to keep your post’s content organized, and they’re great for supporting your article’s searchability. If you’re writing your post in pure markdown, use hashes to denote headers. Your title is the top header (H1) automatically, so your highest-level header should be H2. You can go as small as H6, but I don’t recommend it — if you need to break down your topics into six levels of subsections, you might have more than one post on your hands 😉

If you’re using our rich + markdown editor on DEV, you can add a header by selecting the H button in the toolbar:

Each time you select the button, it will add another hash up to H4, at which time it clears.

More a11y considerations

Headers are important not only to visually organize your content for the sake of your readers, but also to aid Assistive Technologies (AT) such as screen readers in organizing your content appropriately. Here are a few more accessibility (a11y) tips for formatting your DEV posts:

• Add image descriptions to your images.
• Keep emoji limited to the end of a line of text.
• Avoid using fancy characters for font purposes.

Kent C. Dodds

@kentcdodds

You 𝘵𝘩𝘪𝘯𝘬 it's 𝒸𝓊𝓉ℯ to 𝘄𝗿𝗶𝘁𝗲 your tweets and usernames 𝖙𝖍𝖎𝖘 𝖜𝖆𝖞. But have you 𝙡𝙞𝙨𝙩𝙚𝙣𝙚𝙙 to what it 𝘴𝘰𝘶𝘯𝘥𝘴 𝘭𝘪𝘬𝘦 with assistive technologies like 𝓥𝓸𝓲𝓬𝓮𝓞𝓿𝓮𝓻?

18:49 PM - 09 Jan 2019

For more details on why these are best practices for a11y, please check out Accessible Social.

Markdown basics

No matter which post editor you use, it helps to study Markdown basics and double-check your formatting before you press “publish.” Just one backtick [`] can throw off all the code samples in your entire post!

There is a helpful Markdown guide available right in the post editor, and you can learn more about formatting in the DEV editor from the Editor Guide.

One very cool formatting feature on DEV is the use of liquid tags. You can read up on our supported liquid tags from our Liquid Tags Guide. For some examples, check out the liquid-tagged article below:

That's it! Happy formatting. The next installment of this series will be about tone of voice.