DEV Community

Stephan Miller
Stephan Miller

Posted on • Originally published at stephanmiller.com on

Writing a You Go - Technical Article Writing Made Easy

#writing

If you are a working developer like I am, you should never have a problem coming up with an article idea.

Well, I am one and often do. Sometimes I forget the things I write about in this article because they are rattling around in my head. So I panic when I can’t seem to come up with an idea for a technical article out of the blue. Do I really want to write the same article about JavaScript reduce that is available on seemingly 100 other websites?

So with this article, I am trying to get them down on paper and be more systematic in the future.

You might not have a market for the article ideas you come up with, but if you use the methods here to come up with them, there will be an audience waiting for them. And if you want to write the 512th iteration of a JavaScript reduce article, I can show you how to make it better than the others.

Disclaimer: This is a work in progress. I only recently became less of a dumbass and started learning some of these lessons. Writing on a deadline with editors and standards helped with that.

Table of Contents

How to Generate Technical Article Ideas

Write an Article When You Can’t Find Something

I know you’ve been there. You have a Google search open and you’re using Ctrl click to open the results in new tabs, because you can tell from the SERPs that the answers to your question are going in ten different directions. The majority of those open tabs will most likely be Stack Overflow threads, exponentially increasing the amount of things you have to try to fix your problem.

This is when you start taking notes. This is where you can help the next person that is having your problem find a much shorter route to a solution.

Or maybe you are working on something bigger, where you have to have one technology to work with another and you have quite a few resources open trying to figure it out. The point here is that all the pieces you need aren’t all on the same page.

Here are some examples of blog posts I wrote that were born this way:

  • How to Store JSON in PostgreSQL: I discovered I could do this and wanted to learn how. I also discovered when I searched for any specific thing about it, I ended up on a new page. Not one single page broke down everything you could do simply and there were often 2-4 ways of doing the same things, which was confusing. So, I broke it down for myself, writing an article while I did. I get 5-10 visitors a day to this article.
  • Creating an Android EULA Activity: When I wrote this I was new to both Android and mobile development. If you have been doing it for a while, this article would never been needed. It is a pretty simple concept. But when I went to look for anything that would just show be a simple set of steps to do it, I couldn’t find it. So I figured it out and wrote about it. I also reposted it to Medium. For years, the post on my blog and the Medium post were ranked #1 and #2 for “creating an Android EULA activity” and many phrases close to it in Google. There is a canonical tag, so I am not sure how this happens, but I’m good with it.
  • JavaScript Reduce - A Complete Guide to the Only JS Array Function You Really Need: This one I wrote because I knew a lot of developers that didn’t use reduce at all because they didn’t understand it. I remembered being in that boat and I remembered when it finally clicked and knew I had been missing a lot not using this method. I knew I had a lot of competition in the search engines, so I spent some time listing everything I could remember running into dealing with JavaScript reduce and wrote a 3500 word article about it and it gets some traffic.

And if you try 50 things before the one that worked, you could also turn it into a story, mentioning every wrong step you took, because there will be others taking the same wrong steps and searching for why. The trail of keywords (AKA breadcrumbs) could lead them to your post. Here is where I did that:

  • A Tale of Saving a Windows Installation with Linux: This was a rant that I tried to turn into comedy and ended up seeding it with a lot of the keywords you would use if you had this problem for the first time, especially if you had already tried half a dozen things.

This type of thing sometimes happens when I am writing an article for a client and then you just have to roll with it, figure out how to fix the issue, and mention it in the article.

Write an Article When You Do Something New

Jargon is where understanding goes to die. It is a label you use in an industry to abstract away a concept you already know so you can get it out of the way to do other things. And it hides a lot of details that a newbie has no clue about.

When I am new to something, I would rather learn from the person who just did what I am trying to do rather than an expert who knows everything about it and can see 50 steps ahead of me. Why?

Because he already is 50 steps ahead of me and knows not to step on the sketchy-looking board in the bridge that will send me plunging to my death…but doesn’t tell me, because from where he stands, it’s common knowledge.

But it’s not for me.

And when it’s not, sometimes using the incorrect term at the right place beats using the correct term (jargon). And when you spent the last two hours on a “simple” step in an experts article, because of “oh, I thought everyone should know that”, putting that part in your article, explaining it as well as you can, and getting ridiculed by the expert for it is worth it. Because in the end, you will be helping newbies learn and the expert, just confusing them.

Here are some articles I wrote when I realized that I could just turn what I was currently doing and learning into an article.

  • How I Finally Ditched Evernote for Joplin: I had tried this once before but realized that I had Evernote everywhere. In the web, in my browser, in my phone, and in my tablet, which wasn’t the same OS as my phone. So I rolled back. When I tried again, I had more time, but it didn’t really take that long, so I wrote about it.
  • Creating Full Stack Dapps with Truffle Boxes: I have found that cryptocurrency confuses everyone, including developers. So you have money and you can write code that moves it around? What about bugs? Can hundreds or thousands of dollars disappear in a second because of a simple accident? So I started to figure it out and wrote about it.
  • How to Add Search to Your Static Site Generator: I had tried this before with a Jekyll plugin and couldn’t get it to work, but wasn’t too focused on it. Fast forward a few years and I learned about Lunr.js, added search, and the results surprised me. It worked great, didn’t involve third party services, and didn’t take that long at all to implement. So I wrote about it.
  • Creating an Android EULA Activity: Yes, this article kind of fits in both categories. It was something I was doing for the first time and I didn’t find all the information in the same place.
  • A Tale of Saving a Windows Installation with Linux: Ditto for this one.

And when you take coding tests for interview and you have to do something new, that could be an article too. Plus, after you remove anything from the code you wrote that you need to, you already have code examples for the article. I am planning an article on RTK Query because of the code I wrote for one coding test.

Write an Article to Store Your Own Notes

I started a blog around 20 years ago because everyone else was and I didn’t want to miss out. But then I couldn’t think of anything to write about. So I started writing about things I did that I might have to do again. I also thought that other people might find the information useful.

So I wrote articles when:

And eventually after I wrote enough articles about screwing with Google and other things SEO, I got some guest posting opportunities:

Shortly after that, I:

So, just taking notes on what you do can go a long way.

Tools That Can Help With Writing Technical Articles

Along the way, I’ve picked up a few tools that help me get this done.

tabXpert

This Chrome extension let’s me save a whole Chrome session instead of a bunch of bookmarks. That way if an article takes a little more research, I’ll just save it as a session and continue where I left off later.

tabXpert-screenshot

Github Gists

I have to admit I haven’t create any new Gihub Gists in a while, but they can be a useful way to save snippets of code to use in an article. After you create a gist, you can copy the code to embed it your article by clicking a button on the gist page:

Embed-Github-Gist

I stopped using gists in the last few years for this because I just embed my code in markdown now and use css to create the syntax highlighting.

Online IDEs

A gist will give your uses a nice formatted and syntax highlighted version of your code, but an online IDE will give your readers the ability to execute the code. I don’t use these all the time, but they can be especially useful for frontend code you want to show off. Here are some common ones:

  • JSFiddle: The classic JavaScript code playground.
  • CodePen: More features for larger projects.
  • CodeSandbox: At the time I first used it, it was the only one that would run React Native projects. It will also run some other languages like PHP, Python, Rust, and Go.

There are also online environments to execute code other than JavaScript like ideone and CodeChef, but I haven’t used them yet for backend languages. There is even SQL Fiddle for online SQL development environments.

DBeaver (for SQL)

I had to mention this one because I ran into a feature in DBeaver that made SQL-based articles 1000% easier to write if you use markdown. Just select and right click on any table layout in the app, choose Advanced Copy and you can copy what you selected as markdown. If you ever tried to create a table in markdown, you know how much time this can save.

So when you write a query and want to give an example of the results, you can paste them right into the article.

DBeaver-Markdown-Copy

A Quick Screenshot Tool

I do get that most operating systems have a way of creating a screenshot and maybe they have gotten better, but I just haven’t taken my chances lately. I used to use Skitch along with Evernote, but it is no longer being updated and got really buggy on Macs with M processors. Also I recently stopped using Evernote. So I use Shottr now. I can’t really say its the best, because it was the first one I tried after reviewing a few options. But I haven’t looked for a replacement yet so it works for me.

The handy thing about Skitch in the past was that it would store screenshots in Evernote. It was also unhandy at the same time because once you set that up, it stores all your screenshots in Evernote. But this would allow me to start taking screenshots once I knew that I had an idea and come back later for them. Now I create them and paste them in a Joplin note for later use.

Joplin (or Evernote or Something Like It)

Sometimes I don’t get started on the article right away and may do research here and there before I write it. A note taking app with a web clipper and mobile apps makes it easy to do research whenever I can. I don’t really have much of a process for this except clipping the whole page, maybe tagging it with something I’ll remember, and then remembering I clipped the notes when I’m writing the article.

Google Search History

This is especially useful if you are writing an article about a topic because it took you many open tabs and Google searches to figure it out. Just go back through your search history to retrace the path you took. Here you will find keywords, wrong directions you took, etc. And if something fits, add it to your article. TabXpert also saves a history of your last 100 closed tabs per session, so that helps too.

An example is when I discovered the terms “programmatic SEO”. I was doing it as early as 2004 and I just discovered the term this year. I was looking for more techniques on doing what I used to do. I think I started with terms like “data site generation”, “generate SEO site with code”, etc. I ended up using dozens of terms before I ran into “programmatic SEO”. And I am guessing that other people would be in the same boat as I was at some point. But now that I know the jargon, I gave up on my search. But the phrases I used before I found it could be gold.

Editing Your Technical Articles Before You Publish

My old method of writing a blog post was to come up with an idea, write it from start to finish in one sitting, hit publish, and be done. If I noticed a typo, I would fix it. Most of the time I would notice these after I published and I would have to edit it and republish a couple of times.

Now I do things differently, though some things do still slip through and sometimes I skip some of the steps.

What Did You Miss in Your Article?

Now, you may have the best idea for a new article, but I guarantee that there will be others out there hitting the same topic from different angles. And you want to find them to see if you missed anything. You aren’t going to add everything you find and you aren’t even going to think of this in terms of beating the competition.

Instead, you want to make sure you covered everything about the topic from your own angle that you need to to make it complete. I did this heavily on my article on how to use reduce in JavaScript. Initially it was just going to briefly tell how it works and then for examples, show how to replace map, filter, and find with it.

But then I searched for articles that would be similar to mine, and from reading them, remembered when I had searched about JavaScript reduce before, I searched for specific things like:

  • How to flatten an array of arrays
  • How to use reduce with a JavaScript object
  • How to convert CSV to JSON
  • How to use reduce with async/await

And more, so the article grew to about three times its original size. Another option would be to break the article up into multiple articles and interlink them.

You can also check Stack Overflow and Reddit for popular questions related to what you are covering.

And, in the middle of writing this article, I realized that this and other articles I have written recently really need a table of contents, because people could land on the article from a variety of search terms and the table of contents would guide them to the section they are looking for. Well, let me tell you. That change on 4-5 articles on my site tripled traffic in a couple of months.

What Are People Looking For?

This is where you stop thinking about how brilliant your idea is and start thinking about how it will help people and how they would find your article.

  • Does the title describe the content of your article and make it stand out?
  • Do you have headings that describe each section for the people who visit from Google and just want to read part of your article? While I will hit Ctrl-F and search the page when I am looking for something specific, not everyone will and headings with help them find the section they are looking for.
  • Does the excerpt and meta description describe the article well and make people want to read it?

These are all doorways that lead people into reading more of your article or clicking the link to it in the first place.

Does the Article Sound Right?

Sometimes you read what you expect and not what you see, especially when you are reading your own words. Before you publish you should read your article, to make sure it makes sense and sound right. But I have found that using a tool like Natural Reader that will read for me is much more effective, because I am not the one reading it. I just split my screen with my draft on one side and the reader on the other, so I can pause it when I need to change something.

Something I’ve started to do off and on is rewrite the introduction and conclusion by default. The introduction can be the difference between a visitor that continues to read your article and a bounce. And the conclusion might make them want to read another article you’ve written.

Does it Play Well with Google?

This is the part where you tweak words and phrases you use in all parts of your article slightly. Here are some tools to help with that:

And I while I might sometime in the future, I haven’t had to pay for any of these yet to get what I need. After all, I am going to write the article based on my idea, not use the tools to come up with ideas for new articles. I am just checking if some of the keywords I used could be replaced with other, more popular ones.

My Technical Article Backup Plan

Most of the places I get paid to write for either have a list of topics they want to cover or a partially fleshed out idea that I can either accept or reject. Let’s just say that most of what I write for pay is not what I would choose to write, but I do it because of, well, I get paid. And I have been paid for over 1000 articles in the last four years or so.

I think because of AI, this has slowed down a bit. Though, get this, I did pick up a side gig editing technical articles written by AI to make sure the terminology used is the terminology that those in the field would use. And I have actually been paid more doing that than what I would writing the whole article from scratch by most places.

So when I am not writing for pay, I am writing articles like this. And I haven’t yet cold-pitched an article. I am kind of scared to. But I think what I am going to do is continue to use this technique of coming up with ideas when I have time, write the article, find a website where it might fit, and pitch it there. If no one wants it, I will publish it myself.

I take that back. I did pitch How to Store JSON in PostgreSQL to Linode. I wrote it. I submitted to their git repo with a pull request. And I waited a year and watched it sit there. So, I deleted my pull request and published it here. It’s kind of what gave me the idea for this backup plan.

It is also why I am scared to pitch another article. 95% of these places, in my experience, will just leave you hanging. I get everyone is busy, but come on. Don’t list your site as accepting articles and then ignore everyone. And here is my shoutout to CloudCannon for being one that didn’t even if they only told me they weren’t accepting any new articles at the time. Most have ended up on this list:

DBeaver-Markdown-Copy

But what happened in the middle of writing this article, which I started writing in the beginning of March 2024?

  • I got contacted my two companies on LinkedIn and now write for them.
  • Writing picked up with the places I already wrote for.
  • I did take two whole days off, Memorial Day and the Fourth of July, but I wrote the rest of the time.

But this still will be my backup plan.

Promoting Your Technical Article

I have to tell the truth about this. I really have to work on this part. Up to now, here’s what I’ve been doing with recent articles I’ve written here:

  • Publish it here
  • Republish it on Medium
  • If it is about coding, republish it on Dev.to
  • Post about it on:
    • Twitter
    • LinkedIn
    • Facebook
    • Reddit

And that is about it. You know which brings the most traffic: Reddit. Sometimes Medium gets close but that traffic mainly stays there. I can’t say I’m an expert about Reddit, but I can say that it doesn’t matter if Redditors like you or hate you. You only have a problem when they don’t give a shit.

My post about the JavaScript reduce article on the r/javascript subreddit looks like it bombed and I kind of expected it to turn out this way. The title was kind of linkbaity and you had to read the article to see I wasn’t actually suggesting to use reduce any time you touch a JavaScript array. A lot of people I knew didn’t understand it and I thought suggesting it could be used for everything would make people look into it.

But…it got three time the page views of my post about replacing Evernote with Joplin, which got 22 upvotes compared to 0. So yes, if you give developers on Reddit something to nitpick or a controversial development topic, you might actually get more traffic than if you write something not prone to attack.

The post about Jekyll search had limited traction, but it is a pretty niche topic. I used to be scared to post articles on Reddit fearing they might get ripped apart. Now I think that might be the easiest route to traffic from Reddit because trying to write something everyone will love usually results in something so bland, no one cares.

Like I said, I need to work on promotion. Some things I am thinking of doing include:

  • If I mention a library, tool, or software in a post, contact people involved with it about my article. For example, if I hadn’t already been writing an article for LogRocket about RedwoodJS, I could have mentioned on their community site, like this. And I could have done this with the Joplin, Truffle, and Jekyll articles.
  • Find more places like Dev.to and Medium where my articles can be republished or promoted like:
  • Find places where people are having issues that my articles address, solve their problem and link to my article for more details.

Conclusion

So this article took three months to write, because I got busy. It was meant to help me systemize writing technical articles, so when I saw a gap in paid writing assignments, I could jump right into another article. But no gaps came in all that time, so I guess that’s a good thing?

What I did do is test my theory. At the end of each work day, I thought, “What happened or what did I work on today that I could write about?” and there was always something and most of the time, half a dozen things. I never got to those ideas, but that’s a good problem to have.

I also haven’t tested my new plan for pitching technical articles or trying new promotion techniques, but once I get the time to write new articles in the first place, I’ll let you know how it goes.

Top comments (0)

Read next

kkoziarski profile image

NuPhy Air75 V2 - firmware upgrade & troubleshooting

Krzysztof Koziarski -

quovadis profile image

SAP BTP Kyma blueprints

Quovadis -

algieba profile image

[Development Tips] How to Get the Number of Strokes in Chinese Characters?

algieba -

acoh3n profile image

Building scalable ML workflows

Arik -