This post was inspired by a comment I left on @dsteenman's post.
Article No Longer Available
Most of the time I prefer short as I am more likely to read the whole thing. If its set up as a series I am more likely to work my way through the whole series in a matter of a few sessions. Just my preference
I will say though there are certain articles that fit well to the long format. They are articles that folks tend to come back to often as a reference again and again.
Sections
Compelling Introduction
Think about that content that sits above the fold real hard. Make sure that you have some of the juicy stuff right there at the top. Done waste that space completely on your TOC.
Give a small peek into the results right at the top of the post. This will help engage readers and pull them in, as well as leaving a strong impression right upfront. I find this important for articles that I am trying to go back and find later.
layout is key
Either way, you go layout is key. You are not Stephen King, no matter how great of a writer you are, you are unlikely to hold attention like he can. Most folks reading blogs scan articles first. I often scan, then read. If the article is really good or pertains well to me I will read everything, otherwise, I go back and read only the sections of interest. If there are no discernable sections you lost me.
For this reason, you need to break up your post, into sections and treat the heading for each one like you would a title of a full post.
TOC
Table of Contents
A lot of folks responded to Danny's post suggesting a table of contents. For some reason I have never included a TOC in my posts. It's something I am now considering. I am really good at changing layout right before, or after, shipping a brand new post.
semi-auto TOC
As I am highly allergic to unnecessary rework and potential mistakes I put together this snippet that generates the TOCautomatically, just paste this into your console, and paste the results in your article.
// pres F12
// paste this in the console
// get your auto generated DEV TOC
let minHeader = Math.min(...[...document.querySelectorAll('.anchor')].map(a => parseFloat(a.parentElement.tagName[1])))
let addSpace = function (tagName, minHeader) {
if (tagName[0] === "H") {
return ' '.repeat(tagName[1] - minHeader)
} else {
return ''
}
}
console.log(
[...document.querySelectorAll('.anchor')]
.map(a =>
`${addSpace(a.parentElement.tagName, minHeader)}1. [${a.parentElement.innerText}](#${a.href.split('#')[1]})`
)
.join('\n')
)
Break it up
Use headings, images, and blockquotes to break your article up and make it scannable. I treat each heading as an article title. It should be engaging and pull the reader in, but not be clickbaity and irritate them when they didn't get what they expected.
make it scannable! ... treat each heading as an article title
Markdown
Get Familiar with Markdown. Check out this cheatsheet or the reference right in the DEV editor. This is not an article about markdown, but here are the most common tags you need to break up your article.
# H1
## H2
### H3
... up to H6
* unordered
* list
* of
* things
1. ordered
1. list
1. of
1. things
**bold**
_italics_
~~strikethrough~~
👇 Horizontal rules are great a making a hard break between sections
---
DEV also supports these HTML elements for additional flair, use wisely. Some can make for some really jarring style that really pulls the readers eye to and is hard to focus on the rest. I'm talking about you <mark>.
<small>small text</small>
<sup>superscript text</sup>
<sub>subscript text</sub>
<mark>highlighted text</mark>
<abbr title="Table of Contents">TOC</abbr>
Liquid Tags
When Editing a post click the Liquid Tag reference to the right, for a list of everything. The post tag is the retweet of DEV.
{% post helenanders26/sql-series-from-a-to-z-2pk9 %}
{% user helenanders26 %}
{% github forem/forem %}
{% github forem/forem no-readme %}
No Liquid Tag
no problem
There not a liquid tag for everything. While not quite as good you can hack some things with images.
Embeding things without a liquid tag can be quite tricky to do right and get engagement. I often would wrap links around images, but have found this doesn't give the impression that there is really something there. Most of the time I expect it to just open the image.
create your own custom "liquid" tag
[](https://waylonwalker.com/newsletter)
<!-- IF you don't want it full width use HTML -->
<a href='https://waylonwalker.com/newsletter'>
<img width=400 src='https://dev-to-uploads.s3.amazonaws.com/i/9xion9oe68em36mpxiwv.png' alt='newsletter signup' />
</a>
Something I have picked up from @dailydotdev is to style your images like a button with a clear call to action on them when wrapping them with a link.
an example of my No Liquid Tag Hack attempting to make it look like a button
CodeBlocks
Again this is not a markdown post, but real quick wanted to say, Make sure you put the language after the backticks to get nice syntax highlighting.
without a language does not highlight
def hello_world(who):
print(f'hello {who}')
```
**with** a language looks much nicer
``` python
def hello_world(who):
print(f'hello {who}')
```
Here is the comparison in Markdown.
## Article types
As I can see there are several **article types** on DEV. Each have their own considerations and techniques to make them great,
1. [superpost](#superpost)
1. [single post](#single-post)
1. [series](#series)
1. [discussion](#discussion)
## superpost
I think this is what @dsteenman is eluding to with the (+3000) word post. This is the hardest to pull off in my opinion, but if done right it will land you at the top of the search for a long time, in the top 7, and potentially the top 1 for a given tag.
I used to think that every post needed to be a super post that everyone would rave over. I have found personally that attempting to do this makes it so I rarely post and way overthink them. I need to at least make a cutoff time that the post is going to ship.
This can also be the most frustrating, you have put all of your eggs in one basket. If you don't title it right, post at the right time, share it at the right time, it might not take off as you had hoped.
@helenanders26 takes the 👑 as the queen of the superpost. She is the first person who comes to mind when I think of this post type
single post
Your average post. There are a lot of great techniques to making the average post great (some added above). Sometimes they find traction, sometimes they don't. I don't sweat if they don't. I like posting shorter content as its achievable for me and my lifestyle. I can always crosslink them and generate more views/discussion across them.
@taillogs has a good article on his process of writing a good post.
For those struggling to find what to write about, this is a great article from @swyx learn-in-public-hack
series
Using the series tag you can break super posts into smaller ones. This puts fewer of your eggs in the same basket. I typically start a series when I know that I am going to post about a single topic often, but don't have it all laid out. I've been told for these to be really successful it needs a bit more pre-thought.
I do notice that I get a bit of engagement back to older posts every time a new one is posted. so this does help drive engagement by continuously pulling readers in. I am not sure if its quite as good as a link, or liquid embed.
Keep in mind the series component will show the first 2 and the last two without clicking show all. Make sure that the first two really count, they will likely get the most traffic benefit from the series.
I personally put a lot of my content into a series. I don't think through the full series ahead of time very much. I do it because it helps me organize and retrieve my thoughts. I find it easier to get back to the post I want to reference if I can find the series it was part of. I think of it as a tag that no one else can post to.
discussion
Posts just like this one, where the author leads the discussion with an intriguing question or comment but holds back on their opinion. The key here is that the author should engage in the discussion, keep the discussion moving, and provide their thoughts here.
Selfishly this is one of my favorite types of posts to make as I learn the most from them.
@ben is the king of the #discuss post. He is able to get just the right titles that pull people in and generate quite large discussions.
Post what you want to read
At the end of the day YOU are the most important component. Post what you like to read, post what you are able to write. If you struggle to wrap your head around concepts in small posts and have a talent at making rockstar super posts do that. Do YOU
Discuss
What are your best tips, or link an article with the best tips to creating a great post?
<table>
<tbody>
<tr>
<td colspan="5">
I have been writing short snippets about my mentality breaking into the tech/data industry in my <a href="https://waylonwalker.com/newsletter">newsletter</a>, 👉 check it out and lets get the conversation started.
</td>
<td colspan="1">
<p><a href="https://waylonwalker.com/newsletter"><img src="https://dev-to-uploads.s3.amazonaws.com/i/9xion9oe68em36mpxiwv.png" alt="Sign up for my Newsletter"></a></p>
</td>
</tr>
<tr>
<td></td>
<td></td>
<td><a href="https://twitter.com/_waylonwalker"><img width='30' src="https://github.com/WaylonWalker/WaylonWalker/blob/main/icon/twitter.png?raw=true"></a></td>
<td><a href="https://instagram.com/_waylonwalker"><img width='30' src="https://github.com/WaylonWalker/WaylonWalker/blob/main/icon/instagram.jpg?raw=true"></a></td>
<td><a href="https://www.linkedin.com/in/waylonwalker/"><img width='30' src="https://github.com/WaylonWalker/WaylonWalker/blob/main/icon/linkedin.png?raw=true"></a></td>
<td><a href='https://www.buymeacoffee.com/bBdtMQO'>
<img src='https://cdn.buymeacoffee.com/buttons/lato-violet.png' width='200px' />
</a>
</td>
</tr>
<tr>
<td></td>
<td colspan="5" align=center style="text-align: center">
👀 see an issue, edit this post on <a href='https://github.com/WaylonWalker/waylonwalkerv2/edit/main/src/pages/blog/crush-dev-to-posts.md' >GitHub</a>
</td>
</tr>
</tbody>
</table>
Top comments (21)
If you use VS Code, you check out the Marky Markdown extension, which will create a TOC in markdown for you. It has a status indicator above your TOC telling you if it is up-to-date or not as you edit your document.
You can set it to update on save, so it's stays in sync with your headings always. I wrote it recently as I include TOCs in markdown documents regularly, and I don't want to be doing manual updates for this kind of thing! 🤯⛏
Awesome Tip!!! I will definitely be using this. I generally write in vscode, but often tweak and add liquid tags in dev.
You're welcome🙂 If you have any feedback or features requests, let me know! 👍
Great post buddy!
I realized that I don't put a TOC on my articles either because... 🤷♂️
That auto-generated console.log TOC is awesome!!!
I also started thinking that I should only write super posts but I tend to end up rambling a lot so now I'm moving towards single posts, I'm also thinking about making series but then it would just be 2 semi-long posts lol 😅
As an author I lean on the series. As a reader sometimes, I think just give it all to me in one so I don't have to dig. Depends on how tightly coupled the articles are. Mostly I enjoy reading concise thought out posts that gave good headings and get to the point.
This is the first time I have ever put a TOC in an article. As a reader I kinda blow by them and the feel like a waste of space, but I think other people appreciate them more than i do. I also like the point someone brought up about resuming a long article from a given point.
Usually, my real intention is not about the likes, unicorns, or even number of views. -- But it is comments / discussions. (Be it on Dev.to, or on my blog.) Not sure how to generate that...
After all, it is also about building my landscape.
Also, a lot of likes and bookmarks? But how do you measure impact? (However, chains of retweeting may tell something...)
I completely agree, the benefit that I get from DEV is in the discussion section. Posts that have a really engaging discussion are the most rewarding. ♥ 🦄 🔖 Feel good, but I grow the most from an engaging discussion.
Thank you for such an informative post.
Thank you for your the nice comment.
I'll use a lot of your suggestions in my next post & will post the link here.
I would love to get some feedback here if you could spare some time :)
Sure, I took a look at your past articles and it looks pretty good. I would say that you can probably make it a bit more scannable by adding a few more headings, and blockquote. I also prefer to split paragraphs up a bit in blog articles, I believe this is a preference, but it is one way I tailor my writing to the delivery mechanism.
Thank you for looking at my past article, I just finished posting my second post.
Like I said I have used a lot of your suggestions, can you check & see if you find any improvements there?
Here's the link.
I would recommend a few things. Utilize liquid tags to embed dev posts, and tweets rather than simple links or images. You might also want to block out the picture/username of anyone in negativity.
You never know what kind of day they were having and choose to delete their content later down the road when they realize. Screenshotting them and posting elsewhere takes away that choice for them.
"Praise in public and punish in private"
Thank you,
I will look try utilizing liquid tags next time.
Yeah, that's right, I myself felt bad about posting the details, In fact I blocked out the picture & username the very next day I posted my article.
And I really appreciate the way most people respect each other here.
I made a mistake & learned about it, I'll make sure I never do that again.
I'll remember the mantra "Praise in public and punish in private"
That was such a great tip I went back and added it to the article #compelling-introduction
Shows how much I read non tech material 😊. I've seen this reference several times.
👍
🤜
Great article!
I look forward to putting these tips into practice.
Great tips! I don't use TOC (dunno why). I will try to include them in my next posts. Yes, layout is key! For me the biggest learning is to write short paragraphs.
Yes, short paragraphs are a great hack for us mortals (Not Stephen King) to convey our messages in more digestible ways.
I have really shortened up my paragraphs over the past few months as I have started to be more active on DEV, I am learning to better communicate as I go.