DEV Community

Sloan the DEV Moderator for The DEV Team

Posted on • Updated on

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 headings

Use headings 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 headings. Your title is the top headings (H1) automatically, so your highest-level headings 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 headings by selecting the H button in the toolbar:

The editor toolbar, which consists of 11 icons. The sixth icon, represented by a capital letter H, is circled in red.

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

More a11y considerations

Headings 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.

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.

Top comments (22)

Collapse
 
ant_f_dev profile image
Anthony Fung

Any help with these would be greatly appreciated:

  • I've seen some posts with emojis. How do we enter these? Do we find them and copy/paste?
  • I add code blocks by adding three backticks above and below any code I add. This works well, but I've noticed that some code blocks have syntax colouring. How would I add that please?

Thanks in advance.

Collapse
 
desoga profile image
deji adesoga • Edited

If you want syntax highlighting, you'll have to specify the name of the language after three backticks at the top as seen below:

'''javascript
import './App.css';
import Todo from './components/Todo';

function App() {
return (

);
}
export default App;
'''

P.S
I made use of single quotes instead of the backticks so you can fully understand the context of my explanation.

Collapse
 
ant_f_dev profile image
Anthony Fung

Thanks Deji!

Do you know if there's a list of languages somewhere that I can reference? e.g. if I wanted to check if it's c# or csharp, or something else I hadn't thought of.

Thread Thread
 
desoga profile image
deji adesoga

Yes actually. You can check out the link to the Github repo below, which shows a list of languages for corresponding syntax highlighting.

github.com/jincheng9/markdown_supp...

Thread Thread
 
ant_f_dev profile image
Anthony Fung

Thanks again!

Thread Thread
 
desoga profile image
deji adesoga

Sure, you're welcome.

Collapse
 
samuel-braun profile image
Samuel Braun • Edited

If you are on Windows you can press Windows+. (winkey+point) for emojis 😋

Collapse
 
ant_f_dev profile image
Anthony Fung

Thanks Samuel! Looks like there are lots of useful symbols there too👍

Thread Thread
 
caixiangyangcd profile image
CaixiangyangCD

1

Thread Thread
 
caixiangyangcd profile image
CaixiangyangCD

2

Thread Thread
 
caixiangyangcd profile image
CaixiangyangCD

3

Collapse
 
erinposting profile image
Erin Bensinger

For emoji, I use a Mac app called Rocket. As a professional Social Media Manager, it makes the emoji part of my job a lot easier! If you're not on a Mac, I'm sure there are other options out there.

I also recommend Emojipedia for copy-paste needs. It's comprehensive and very informative as it relates to accessibility concerns.

Collapse
 
ant_f_dev profile image
Anthony Fung

Thanks Erin!

I'm on Windows, but Emojipedia certainly looks really useful - being able to search seems like a huge timesaver.

Collapse
 
erinao profile image
Erin A Olinick • Edited

This is super helpful. Thanks for the a11y resources for online content best practices. Please share any others that you reference often or that you think would be useful!

Collapse
 
moopet profile image
Ben Sinclair

I think the other big one is not to use screenshots of code. You know, things like snippets made with Carbon.

Collapse
 
rachelfazio profile image
Rachel Fazio

YAY! Love to see this

Collapse
 
kevthedev profile image
Kev the Dev

I like to use ChatGPT to proofread my posts which often helps with formatting!

Collapse
 
sloan profile image
Sloan the DEV Moderator
Collapse
 
tbroyer profile image
Thomas Broyer

Hey @sloan, I'm not a native-English speaker but shouldn't that be heading rather than header?

Collapse
 
sloan profile image
Sloan the DEV Moderator

OMG. You're totally right — I am a native English speaker, but clearly it's hard for us too 😆 I'll edit this. Thanks for the note.

Collapse
 
algodame profile image
Chiamaka Ojiyi • Edited

Thanks for sharing. How do I create a series on dev.to and display the series links in subposts on that same series. Just like you have done in this post

Collapse
 
sloan profile image
Sloan the DEV Moderator