Today, I drafted a technical blog post on a topic I had been thinking about all week.
As of now, I am at 1600 words, including code samples which seems long.
This has me thinking about the balance between being concise and detailed enough to be useful.
What are your thoughts?
Top comments (13)
Great topic!
I generally aim for around a "three minute read" divided into four to five paragraphs, an intro and conclusion. People like to skim over a post so I aim for bite-sized posts.
Any more than that and I consider splitting it into multiple posts. Sometimes this makes sense, other times it doesn't but that's what I aim for. This sometimes makes a nice series that I can post over a few weeks and build on.
I use this tool (wordcounter.net/) to get an idea of my reading time and other stats. Looks like 1600 is a six minute read. I'd consider dividing it into two but it completely depends on the content. My last post was an eight minute read but there was no logic split point so I left it as it was.
What are your thoughts Shannon?
Yup, I'm using Grammarly as my editor and it's saying 6-8 mins for a read time. I probably have more fluff than I need (clarifying that something can be done this way or that way, with code examples) but I do not see a logical split at this time either.
I'm doing a write up on finding the most common item in a has many through model association in Ruby.
A shorter version could be, this is the code you need, here's some quick points on what's happening, but that doesn't seem helpful. There are some small tangents that clarify what's happening within some functions (like .inject. It's sort of mysterious, so it felt important to explain what is doing what. I learned a lot in the process).
I could end is as is, and do a second post on implementing the method, what you can do with it, but that seems less relevant since the how/what would vary depending on someone else's app/model set up.
Sounds like it makes sense to make it a long read. There's nothing wrong with that and it sounds like a great topic to cover all in one go.
Looking forward to reading your post :D
It depends, there are people with different needs. Some will prefer a short review of a technology, but others want an in-depth analysis.
So what should you do?
Just don't care. Write an article that you'd be happy to read on that topic. If it's a superficial overview, write that. But if it's something long and detailed, work on that! Don't worry about the others, there will be people interested.
Not caring is good advice :)
I think the balance between concise and detailed is where detail is expressed in a concise manner, and I wouldn't focus on the length per se, but rather on whether the length is appropriate to the amount of ground covered. In other words, it kinda depends!
You can stop with adding more and start to edit it.
You should ask yourself these questions:
Have you pick a title, who will attract anyone to read it?
Does that article provide value to your reader be it a perspective or solving their problem?
Is what you are writing evergreen (It remains relevant after technology changes)
You can edit and keep it to 1400 - 1500.
How long did you set aside to write and edit it?
It's very easy to overshot when you are writing.
So focus on spending the same amount of time you write to edit your articles as well.
Good questions!
I have a working title of "Finding the Most Popular Item in a Has_Many, Through Relationship" but I am not sold on it. Will it add value? For me, yes. I learned a lot more about what was happening in my code while writing this post. Will someone else find it useful? I hope so, but it's hard to say for sure.
I spent 6+ hrs on and off writing it yesterday. I want to get faster/better at this.
It's alright, I started out with just setting aside time for myself to write and you get faster after multiple times.
I started out with just high-quality articles that take about 3 - 4 hrs.
My best advice is to focus on documenting with another person in mind and consistency is key by sending yourself a deadline or number of articles to write per week.
I usually use Grammarly to help me to edit my articles.
The other way is signing up for courses like Simple Programmer's blogging course which I went through it twice to get better in my fundamentals.
Depends on the topic I suppose!
I'm always worried when writing technical blogs whether or not I am waffling too much.
In the end, I err on the side of providing as much detail as possible, so the reader can understand what I'm trying to say. Sometimes it's ok, sometimes it doesn't work. I guess that's part of the fun 😂
I am slightly ADHD ;)) so for me I like short 2-3 minute reads.
I wouldn't worry too much. People skim, they re-read, they do a little dance.
Be sure to have some decent headings to allow better skimming.
Possible submit two articles.
Yup! I have some headings, a brief intro and a brief outro (which I may cut and reuse for another post).