7 Reasons to Panic When Writing a Tech Blog Post — and What to Do About It
Ok, full disclosure: it’s the first time in my life that I’m launching a tech blog for my team. I desperately want it to be a great, well-referenced and widely admired blog, a reliable source of technical knowledge, cool coding tricks, productivity tips and, more generally, entertaining and yet informative coffee-time reading.
The problem? Well, I don’t exactly have a team of experienced technical journalists as colleagues. Experts as they are in web development, data science, dev ops and what not, they can hardly be credited with exceptional writing skills. We do, however, have one writing expert: our Content marketing manager, Lexane, whose worst blog post is still better than all of Shakespeare combined (check this one out!).
So we came together and organised a little meeting where we tackled the main blocks that a tech person may come across when getting started in blogging. One of the people in the room asked us: “Are you going to make a blog post out of this presentation?”
Well, why not? Here is an adaptation of our presentation: the 7 reasons to panic when you are a beginning tech blogger… and the solutions to all of them.
Problem #1: I don’t know what to write about
First problem: “I really want to write a post, I promise I do, I just don’t know what about!” Some people have a vague idea that they often discard as one of no interest, some are just lost.
Here’s a working strategy that has just one drawback: it leaves you with almost too much topic choice (but for an aspiring blogger nothing is better than a well-nourished backlog anyway).
So, what’s the last thing you were passionate about at your job? Something really cool you did or would like to do? A new technology you tried? A question that you’ve always wanted a colleague to answer but were too shy to ask? (mm technical question of course) Something that didn’t work out as planned or at all? These are all perfectly valid sources of articles that people would like to read.
Depending on your level of proficiency in the topic, what needs to be adapted is just the imaginary reader. Let’s say, you take APIs. Whether you’re a seasoned expert or are just discovering what it is, your target will change, but the subject matter will stay the same. Compare “How is an API different from an IPA and why it’s important in software development” or “Domain driven approach to a recommendation API service”. Not the same target audience, right?
If you think the angle you’re approaching the subject in question isn’t interesting / advanced / fancy enough, ask around yourself. A fellow colleague, a product manager, a trainee or a non technical colleague will all give you different answers about which facet of the problem to tackle — please listen to them, they are the voice of your potential readers.
Some team members told us that everything they could write about has already been written about maybe a thousand times. This is actually a GREAT sign people are curious about the topic. Add a personal experience touch, give several relevant examples, an opinion you’ve formed — and you’re good to go.
Another technique that works wonders is to view the subject through a prism of a highly fashionable technology. Add GraphQL into your API post, or make it Agile API building — hype words aren’t just words, they are signs of what interests your readers most. As a side benefit, you might discover some interesting things while doing the research!
Problem #2: I don’t know where to start
Second blocker: coders rarely know how to tackle this whole writing business, so they never even start. What happens after you more or less find your holy grail of the idea?
First of all, it’s a good plan to get rid of the “more or less” part first. The idea needs to be clear in your head, so start by putting it down in a Google doc (you’ll understand why there a little later). I’ll stick to the API example, since I love them so much. So, you know you’ll be writing an “introduction to the recommendation API service implemented last month with examples of the architecture, aimed at backend and front end developers working on similar architectural problems”.
It’s a good place to start.
The next thing you’ll need would be a very general draft of what you have to say. The common “introduction — thesis — antithesis — synthesis” schema put into human readable chapters.
The transition should be logical, so that any person with relevant background could understand why and how you arrived at the given conclusion. Don’t be too detailed — just a general idea would fully suffice.
Once this plan is ready, take each section one by one and fill it with raw information. The copy-pasted blocks of research you used, definitions you find necessary, bits of code to illustrate the idea, your very blueprint-like notes on the subjects — anything will do. Don’t make it pretty, just dump everything in. No censorship, no editing, no rearrangement — pure information.
Ok, now you have a Really Long Document, and it’s time to give it some shape. First move your information around to see where it feels most relevant. Cut the long (and useless) passages without hesitation, insert your thoughts and comments. If certain bits feel out of place, maybe you don’t need them at all (stay focused! You have your crystal clear subject on top of the page!).
Some parts won’t come out as naturally as others. No panic, that’s ok to leave placeholders and To Do notes to self, just the same way you’d do with the code. Missing information can be completed later (I believe you’re very familiar with Google and Stackoverflow, right?), the writer’s flow comes and goes!
Once you’re happy with how it’s all turning out, share your writing with a couple of your nicest colleagues for feedback and editing (that’s why you needed it to be a Google document… Although now that I think of it, why not a Github repository?). Don’t forget to be critical of their comments, not all changes are necessarily good changes. Let your common sense guide you and just make it a perfect post you’d like to read yourself!
And that’s it! You’ve got the fun parts left — the right title and the pictures to add, but we’ll talk about them below.
Problem #3: Help, I keep getting distracted!
If you’re anything like Lexane and I, you may start writing… and then get tea… and nibble on a cookie… and think about the laundry you should do tonight… and bet on the next World Cup game… and talk to the person next to you… and never actually write a whole paragraph in your blog post.
Our first piece of advice is to change your environment when writing. The most efficient way to do so is to physically change places: go to the cafeteria (outside of peak hours) or book a meeting room, for example
If you have to stay at your desk, or would rather stay there, then listen to music you don’t usually listen to — try to stick to music without lyrics or with lyrics that you can’t understand. Try to at least turn Slack and emails off for fewer reasons to get distracted.
In fact, this “I keep getting distracted” issue is really much bigger: it’s about taking the time to write something good.
Block time off in your calendar to be more productive. If you don’t book time and think you’ll do it “when you’ll have time”, you will end up waiting forever, because the inspiration might not come to you, and you’ll always find something else to do.
Don’t book too little time: you want to be efficient and be in the zone, not try to get into it and have to go back to your usual work as you were about to start being efficient. Don’t book too much time either: more than an hour will make you tired and unproductive. Booking one hour twice a week is a good rhythm.
Once you are in one of these time slots, do not do anything else. Got blank page syndrome? Yeah, we went over that already. Write something stupid that you’ll edit later. It’s fine.
Just keep writing until you are back on track, it’s all that matters. Don’t censor or correct yourself, just let it flow; you’ll edit (or, better, get your blog post edited by someone else) later. In the same vein, don’t feel like you have to write a comprehensive text from the start: just leave blank space to come back to later if you have a hard time with part of the writing.
Finally, find time-saving opportunities. For example, co-author your post with someone else. This will allow you to discuss things and share the effort, it will go much faster than doing it all yourself! (Can you figure out who wrote what in this blog post?)
Problem #4: I’m pretty sure my blog post sucks
You’ll get better.
I was just talking about co-authoring a blog post. Let’s make this a rule of thumb: don’t work alone!
Ways to collaborate with other people include:
- Having a Slack conversation of someone you could be writing for
- Don’t focus on spelling and grammar, especially if you’re bad at it. Let someone else edit your.
- Try new formats, like an audio recording.
- Share your draft to potential readers (colleagues, friends who hold the same job…) before posting, so you get more feedback
- Really, really don’t want to write, but you do have experience? Why not reach out to someone who enjoys writing and ask them to interview you, so you can combine the writing & technical skills?
Rely on lists, make short paragraphs and short sentences. Make everything light and readable, and don’t feel like you have to be formal (this is a blog, not an encyclopedia) — or funny. If you’re comfortable with cracking jokes, good for you! If you aren’t, it’s absolutely fine — the quality of the content is always more important than the way it is presented. (Unless you do content marketing, Lexane says.) Just think of how you would say the same thing to someone on your team, and roleplay the hell out of it.
Problem #5: I’m really bad with examples
There are a lot of people out there who will completely ignore what you wrote and only focus on the examples you provide. Deal with it: make your examples amazing.
There are several different cases in which you’ll need different examples:
- If you don’t need context: make up a funny and simple example that doesn’t include anything unnecessary. Bad at creating funny stuff? Just use cats. Even people who don’t like cats enjoy a good cat example.
- If you need to present context: use your own code, if it isn’t confidential. The good thing with this is that it’s real: people relate to it and know that you’re not making it up.
- If you are making a series of examples: make everything related. Superheroes, the Beatles, football… anything, really, as long as your blog post has examples with one main theme.
- BONUS: Whatever type of example you’re making, if you want to go above and beyond, you may want to look for an example inside an open source project that you care about. It’s a great opportunity to showcase their work!
Problem #6: I’m also really bad with titles
Let me admit something. Among my last read articles you would find the following: “The man who created Internet has some regrets”, “People who are afraid of food” and “How to build an autocracy”.
While these might be somewhat revealing of my personality, the only thing they have in common is a cool title. Technical posts are no different from any other piece of writing, which means they are judged, so to speak, by the cover — and a title is its most crucial element.
Careful, now I’ll teach you something bad (but it’s for a greater good!).
Go to Buzzfeed and check out their recent headlines.
Headlines I said, not the posts!
See, it’s rather hard to resist clicking. You’re looking for the same effect, this irresistible desire to read your article. Don’t be misleading, though, people want to know what they’ll be reading about. The subject you formulated at the very beginning of your work should be of help here. So, remember: make it funny but still subject-related!
Here’re some examples you could use for inspiration:
- Are your refactoring habits normal?
- What Kim Kardashian doesn’t know about event sourcing! (the exclamation mark is optional)
- 12 ways to make your React application sexier
- What the hell is going on with the production database?
- Secret Gross Things Every Developer Does (With Photos)!!!
Problem #7: Where do you find cool illustrations?
Your article is ready to go, but it looks like one big lump of text. Time to add images into the blog post until it’s actually readable.
There are three main type of visual elements you can include in your blog posts:
- Still images
- GIFs
- Colourful and light code snippets (yes, seriously)
The first one is probably the most complicated one, since you can either use your own images or non-copyrighted images, and they are not all that easy to find. Libraries include:
- Pexels
- Unsplash
- Some of the pictures on Wikimedia Commons — check individual Creative Commons licenses.
For GIFs, things are much easier: there is an unspoken agreement that more or less all Giphy GIFs can be used in a blog post without regard for the copyright. Cool. Just don’t overuse them — they can get a bit overwhelming.
Finally, don’t underestimate the power of colors to improve the look and feel of your blog posts. Sometimes, just highlighting a few words and using syntax coloring will do the trick: try it out!
These were our main tips for getting our developers started with tech writing. What do you think? Did we miss something important, or did we make your life better? In any case, your feedback will be appreciated: share & comment!
