Most developers have to deal with writing documentation, blogs, or other content at some point in their career, and it is in fact, necessary for building great software. Documentation is the first feature that the user interacts with because that’s the first thing we look for when trying to solve a problem. However, it often lags, not because developers are not invested in it, or because they’re not good writers. It’s because many of them don’t know how to do it correctly.
In this article, we’ll be sharing some of the best tips and tricks to make writing easy and effective for developers.
What to write about
This is a frequently asked question by developers as many of them live by the idea that the code should be self-explanatory, however, they often miss the argument that not everyone else is well-versed with code, and while having their first experience at using some software, they might face issues. This is where good documentation, blogs, and other content comes in.
Here are some of the ways that can help you determine how to keep running a continuous production line of ideas for writing about your software or the tools and technologies that you use for development:
Maintain a log of your ideas
A simple trick to combat the anxiety of what to write about is to maintain a log of your ideas. You can use any project management tool or Kanban board such as Notion, Jira, Trello, Asana, etc for keeping track of your ideas. Anytime you get a new idea, you can log it as a new task and even use different project types to classify or categorize these ideas such as:
- Ideas for my tech blog
- Ideas for my travel blog
- Ideas for my SaaS blog
- Business ideas
- Conference talk ideas
This would mean that whenever you decide to write, you already have a bunch of ideas waiting for you.
Determine the platform
The driving concept for your writing is to get your knowledge to the readers. Thus, the reader’s intent and interest is an important factor when writing a specific piece of content.
Understanding your reader’s intent will be helpful to write content that serves people better and is discoverable in the right place. For example, you are likely to go on Twitter or Instagram to find funny, relatable, or inspirational content and not educational content. Meanwhile, you would be searching on Google when you’re looking for a solution to a problem. This is why tutorials and other informational content can do well in search, provided that you have set up the SEO up to the mark.
Validate your ideas with research
Just having an idea is never enough, it’s always important to validate the idea by doing some research on the topic. You can do this in a lot of ways such as - discussion forums on Facebook, Discord, Reddit, Twitter, etc. It will also give you an idea of the platform on which the people who might be interested in your content spend their time on.
However, there are a few glitches to this way:
- As you are browsing through the ideas of other people, there are chances of getting a bias or being influenced by their opinions that might affect the originality of your content.
- A lot of content trending on a platform might be because of the existing audience for an author, brand, or publication.
This is where the concept of SEO drops in. An SEO-optimized blog can attract thousands of visitors to your content for countless weeks, months, and years. Moreover, it can provide an objective way to research and evaluate topics that can be written about, also known as Keyword Research.
How to make SEO your superpower
Before we talk about how to make SEO your superpower, let’s talk about what exactly SEO does. SEO is a way of making sure that the search engines understand what your page is about and that it contains quality up-to-date information from an authoritative source and will answer the question that the searcher had in mind (reader intent!!!).
Unlike Twitter, where a tweet can attract an audience for a day or two, a good SEO can assure you consistent traffic even after months and years of publishing your content.
Here are some of the basic steps to ensure that your content is SEO-friendly:
Discover keywords
The first step to making your content SEO-friendly would be to know relevant keywords. It’s always a good idea to search for keywords using tools like Keywords Everywhere to know about the related keywords and their search frequency.
Niche down to what you can write about
You can use tools such as **KeySearch **and look for keywords that you can rank for.
Finding the tail keywords
Tail keywords are related keywords that can help you make a more complete blog post.
The best way to use these tail keywords in your content is to make a list of at least 10-20 keywords at a minimum and try to use them as you write along. They don't all need to be sections or perfectly related to your topic.
Where to use these keywords
You should naturally use those keywords in some places, such as:
- Your meta title and description
- Your subheadlines
- Your first sentence or sentences
- As the anchor texts on internal links from your other related posts to the post you're writing
- Your image file names and alt tags (just remember the alt tag's primary use is for accessibility reasons)
- Throughout your paragraphs
Include External Links
You should always link to websites with more resources on related topics to tell the search engines that your content is a complete resource on the topic and thus, don’t hurt its chance at a better ranking as Google uses links as a way to determine a website's authoritativeness on a topic.
However, be cautious not to include the links to the content that might be competing with your content for the top spot in the ranking.
Write a headline that could turn heads
Your headline doesn't need to be clickbait to be a compelling headline. It should be descriptive, succinct, and accurate. Here are just a few ideas for our example:
- The Next Big Thing in React JS
- This Week's Top Stories About React JS
- 13 Things About React You May Not Have Known
- The Biggest Problem With React, And How You Can Fix It
- 7 Little Changes That'll Make a Big Difference With ReactJS
The click-through rate on your headline is one of Google's more important factors when deciding how to rank your content. But headlines are also important for promoting content on social media: You might have awesome content inside, but if your headline sucks, no one is gonna see it.
Instead, get creative with your headline. Spark interest. Be concise. And then deliver on that promise with an awesome blog post. It’s always great to have multiple versions of your headlines before deciding on anyone.
Make your content easier to skim through
Nobody wants to spend a lot of time on reading a long post, most of your readers want something that they can skim through easily and understand the crux before getting into further details.
You can try and use these techniques to optimize skimmability of your content:
- Use Call-out boxes for important points and take-aways
- Use shorter sentences and paragraphs
- Use lists and summarizes (think: TLDR),
- Use plenty of headlines and sub-headlines
- Bold out key phrases, quotes, tips, warnings, etc.
Be concise and hold the attention
Always start with a brief intro where you introduce the breadth of the post’s content so that the readers can decide whether it’s for them or not. This is where your chance to hook the readers lies.
What is a hook?
A hook is a half-told story that raises a question and then teases with only a part of the answer. This is what acts as a key to holding the reader’s attention through any content.
Hooks serve the following two purposes:
- They compel the readers to continue reading, switching on the storytelling machinery in the reader’s mind
- They help you identify what’s interesting and novel to write about.
Hooks can be presented in the following ways:
- Questions: Posing an interesting question, but not giving a complete answer at once.
- Narratives: Sharing the start of a narrative but withholding the conclusion
- Research: Highlighting the research findings, but only a small portion of it.
- Arguments: Making an unexpected claim, but not explaining how that is true.
Make it relatable and humorous
Readers love to read relatable content, especially if it involves some common experiences, miseries, or know-hows. A bit of relatability, vulnerability, and being open can go a long way in establishing trust with the readers.
Moreover, humor is a great part of making people interested in reading what you have to say. It also helps you connect with the readers in a friendly context. Thus, make sure to include memes, gifs, and images that can twitch a nerve and make your readers laugh.
Always End on a Call-to-Action
Calls-to-action is a great way to spark a public conversation about your content and get feedback. Never leave your audience hanging on the question of what next, always say goodbye with a call to action such as - asking them to follow you on Twitter, check out your project, or leave a comment sharing their experiences, etc.
This was all for this article. I hope you found it helpful. In case I missed something, feel free to add to these tips and tricks and make writing easier for your fellow developers.