DEV Community

loading...
Cover image for How to write technical content
This is Learning

How to write technical content

armandotrue profile image Armen Vardanyan ・12 min read

Original cover photo by Jan Kahánek on Unsplash.

It is early morning, you grab a cup of coffee, turn on your computer at work, scroll through emails and notifications, and also open up some favorite resource of yours and try to catch up with the latest developments in the world of software engineering. You read several interesting articles, find out some useful, but less known features of your favorite framework, or some obscure, but fun technique, and move on to your everyday work.

Later that day, you stumble upon a problem, figure out a solution, but are not sure if that is the best thing you can do about it. You google the problem, and find a great article with nice examples which helps you overcome your challenge in an elegant way.

In the evening, before going home (or to the kitchen - in the age of COVID-19 and remote work), you scroll through Twitter a bit and encounter yet another article which describes some interesting use case that another developer had to deal with.

During the day, you have read multiple articles, and your experience in the field has grown a bit. Want it or not, but we, as developers, consume huge amounts of technical content created by other developers - people just like everyone else, but with a passion for sharing knowledge and experience. And if you have read this far, chances are you are interested in starting contributing back and creating your own technical content. I have been doing this for the fifth year now, so let me try and give you, an aspiring creator, some insight into what challenges you might encounter on that journey, and how you can overcome that.

Where to start?

Creating content can sound challenging and even intimidating; and trust me, the beginning of that journey is somewhat uneasy. You may experience anxiety comparable to stage-fright; “What if the content I am about to create is not necessary?”. “What if I get criticized?”. “What if it is just not for me?”. All those are very normal questions that an aspiring creator will ask themselves, and I have gone through that too. To understand how to proceed, we need to answer three key questions: Why? What and How?

The Why?

At the very beginning of any endeavour there is a reason, a drive that makes us try and create something, and reach a new level of experience. So, before starting our journey into writing articles, tutorials and other content, let us examine why we want to do that, and what exactly it will give us back.

Learning and growing

Let’s start with how writing content will benefit you. There is an old saying - “if you want to understand something better, explain it to someone”. Some students use this technique to master sciences they study

  • there are people that will essentially tell something to themselves (sometimes out loud), which helps them gain more insight into some topic and remember the details. Writing is the same in that sense - but better. When we write tech content, we experience the things that we have created another time, helping us see it from different points of view, which eventually, even if we don’t try hard, makes us more experienced with the subject. So first of all, writing tech content is very beneficial to your own experience and knowledge.

Gaining popularity

Now let us explore a bit more “egotistical” side of writing content. If you write content that is clear, understandable to most and, most importantly, helpful, you will attract attention towards you, the author. Now this is not necessarily something everyone wants - for me personally, even if I help exactly one single person, then my effort was worth it. But the good thing is that writing content does not necessarily mean you now have to tweet tips and tricks all the time - writing is a voluntary contribution to the community, not a burden. But now and then it will also help you meet awesome new people - something I will cover a bit more in the next paragraph.

Establishing connections

Writing content will help you meet new people. Lots of people you meet will be plain amazing - strong experts ready to help you out. I personally met dozens of great people - cannot even list them in an article, and they have influenced me positively a lot. You will meet them too, and it has a list of great benefits:

  1. Meeting new people opens you to new knowledge. Talking with other professionals in the fields will help you discover things you didn't even know in an area you thought you knew thoroughly. It is a great opportunity for personal growth

  2. New people will also open you to new content. Chances are, you will meet other content creators and get exposed to their thoughts and experiences, which will again inevitably help you grow

  3. It is good for finding new challenges and jobs. The more people you know, the more you are exposed to great job opportunities, chances to participate in open source work or solving challenging problems

Sharing is caring

We have covered the benefits you will receive when you start writing, but now let's focus for a while on the good that you are making for the community. As I have mentioned, for me the most important aspect of writing is the opportunity to help others. Modern tech industry is built on the hard, but voluntary work of thousands, if not millions of contributors. Frameworks and libraries that we use in our day-to-day jobs are often built by people like us - enthusiastic engineers that want better tech and better working environments (and who will argue that working with better code is less stressful?). So, working on creating content for other developers is our way of contributing back to a community that has undoubtedly helped us grow and become who we are now.

The What?

So, it is possible that after reading the previous chapter, you are already dead set on the resolution to start writing technical content. But then comes a harder challenge: what exactly should I write? Of course, this is a more complex question, but I will try to present some advice on it.

Warning: even if you already know exactly what content you want to create, I still recommend reading this chapter. You might gain valuable insight, and even if it is not useful right now, it will be in the future. One day, you will eventually run out of ideas, and this chapter is aimed at helping you find new ideas for content easier.

Catching ideas

You write some code at your job, fix a problem, and realize you have used an interesting solution that is worth sharing with others. Or maybe you uncover a bad pattern of code that is used throughout your application, and want to write a piece explaining why it is bad and how to fix it.

But there is a slight problem - you don’t really have enough content to write a thoughtful article, and just one example will be a bit shallow. You might try to imagine a scenario or an example, but more often than not those attempts will be futile - examples you come up might be just too contrived or unrealistic. So what, forget about this idea and move on? The answer is definitely not. What helped me greatly is the following: every time I encountered an idea worth sharing in an article, but without enough content to write it right away, I would write that idea in a special note, come up with a working name for my future article, and wait. During the following days I would naturally encounter examples and thoughts that would reinforce my article; I would add those to the note too; and so on until I had enough bullet points to actually write the article. Sometimes that process would take longer; my article titled
RxJS: the Unexpected actually took several months to form in my mind (and my note) until it finally became an article.

Now you might think that this approach might help in, say, 30 to 40 percent of ideas you have, but in my experience, that is simply not the case. Out of 10 ideas that I wrote down in my notebook only 1 did not ever become an article. So think about ideas for content, but don’t ever push yourself too hard: ideas will be coming to you naturally all the time, it is just important no not let go of them.

Don’t underestimate the power of use cases

There are lots of types of articles and written content out there. There are tutorials, best/bad practices articles, in depth explanations of stuff works under the hood, and so on. But for me, one of the most important types of articles that I ever read are “use cases” articles. What is it? Simply speaking, it is a story about how a certain developer encountered, analyzed and fixed some problem they faced. And the thing is, those articles are very beneficial both for their writers and readers simultaneously:

  • What do readers get: possible helpful guidance on how to face a certain problem, coupled with a safeguard against writing an unnecessarily complicated solution and then refactoring it + extended knowledge and experience

  • What do writers get: an opportunity to really reflect upon the problem and remember the solution + as a bonus, coming up with ideas for such articles is really easy, as we are essentially facing use cases all day long in our day-to-day jobs.

So next time you find out you’ve run out of ideas, try to reflect on the code you wrote in the last week; it can be very much possible you have faced an interesting problem and came up with a solution worthy of an article.

What if the content I write already exists?

One question that often bothers content creators is whether their content is even worth writing, because someone else has already explained that. Obviously, this is a valid question: repeating the same thing others said seems not to be the noblest thing. But as they love to say in Armenia, “repetition is the mother of knowledge”. Consider this: I have written my article about Angular Bad Practices almost four years ago. Have you read it? Has everyone you know in the Angular community read it? Will they probably encounter that article in the future? If the answer is no, no and yes, then here is another question: will someone benefit from reading an article that reiterates some of the points provided in my article + some new advice? Now, when you write any content, chances that everyone who needs that content will, in fact read that content, are really slim. This means, some important topics need repeating, especially things like best practices, existing approaches to solving common problems and so on. So be calm: even if someone has already written about the topic you find interesting, you still can have a very valuable input.

The How?

Now at this point, we already know that we want to create content, and maybe what content exactly we want to create. But how do we make that content really good? How do we engage the reader, but at the same time provide valuable information without being too verbose or “on-the-nose”? Don’t worry, there are things you can do to achieve this.

How do I explain something?

Explaining something is the core aspect of writing technical content. It is essentially why we write anything at all: we try to convey an idea and make sure it is understandable by the reader. How do we achieve this? Here are some bullet points to help you:

  • Start from the problem. Before explaining any approach, start with presenting the issue that our idea is coming to help with. Present code examples that show exactly what the problem is, so it also makes people identify easily where in their own applications that problem arises

  • Provide good, but simple examples. Don’t include any code that is not relevant to the problem and the solution, even if it makes the example “prettier”. Make sure the central idea are, in fact, in the center of the example

  • What I personally find very helpful is providing two examples per approach: on with “bad” code that has problems, and another one that shows the “good” code, which is the goal of our article

  • Write comments inside the code examples; now you might think “am I not going to elaborate on the example in the article itself?”. But the thing is, code comments help illustrate exactly where in the code the cool stuff is happening, or a problem lurks, so it can be more valuable and attract the reader’s attention to the most important spots

Now let’s understand how we can present the content in other ways.

How do I present something?

Words are very cool. Groups of symbols that convey meaning are probably the most important invention of humankind, allowing us to reach the heights of the civilization we enjoy today. But the thing is, sometimes words are simply not enough. “Show, don’t say” is a very old saying, and has lots of truth to it. Help the reader visualize ideas that are hard to convey by using only words. Create graphs, use gifs, or charts. One of the nicest examples of visualization are RxJS marble diagrams. Use tools like this to create powerful representations of topics you write about, and you will find your articles become way more helpful

Respect the reader

Language we use is also very important. You don’t want to sound condescending, or too “smarty”. You are there to help the reader, not establish yourself as a knowledgeable person. Here are some tips how to make your content more friendly:

  • Use the word “we” instead of “you”. This creates an idea that we are learning together with the reader, and respect them and put on the same level as ourselves. Now you might ask “but you have been using “you” all the time in this article!”. But this article is me sharing my personal experiences with you, the aspiring content creator, and you can be sure you have my utmost respect simply for wanting to contribute to the community.

  • Avoid words like “simply”, “just” and “easily”. Those words create the sense that those ideas you explain are primitive. And even if they are for you, it might very well not be the case for the reader. If you state that an idea is simple, but the reader still did not understand it, it will subconsciously create a sense of inferiority and feed into their anxieties. Again, treat the reader as an equal, don’t assume they have the same experiences as you have, be mindful.

  • Don’t use condescending language about “bad” code. People write code with bad practices every day. I have, and you have too, and every single person in tech. People that (sometimes, or even often) write bad code are not bad people or useless employees, they are people just like me and you, working in a huge tech industry and looking to grow. Again, you are there to help, not disenfranchise.

  • Respect people’s opinions and don’t allow inflammatory comments to hurt you. Some people will disagree with what you write in your article. After all, almost everything we have in our minds are opinions. Respect their different opinions, engage them in a discussion, present points and listen to them, but always in a mutually respectful environment. Remember, even if you present new, strong arguments, they still might not change their opinion, and that is completely okay. You try to share knowledge, not convince and enforce. One unenjoyable part of creating content might be people writing inflammatory and condescending opinions. I have encountered some people like this, thankfully not very often, but here is an important thing: continue being respectful to them even if they present their ideas and opinions in a way you don’t like. (unless they outright offend you, in which case ignore or block them - but don’t ever engage in a disrespectful exchange).

How do I make sure people really understood me? (or the power of feedback)

After you have written an article, your readers will start commenting on it. We have covered that a bit in the last paragraph, but we only addressed opinions. In most cases, comments that people leave will be not opinions, but questions. And it is very important for you to try to stay in touch with the readers, and provide more insight into your ideas. Don’t push yourself too hard, it is not required to answer the questions in under five minutes; but do your best not to leave any questions ignored.

Bonus point: involve other content creators

What really helped me grow as a content creator is having other content creators review my drafts (and of course reviewing theirs). As a matter of fact, lots of advice presented in this article is not my own ideas, but rather something that I have learned from my fellow writers. So, a very nice opportunity to start writing content is to join This is Learning / This is Angular, a community I am also a member of, filled with awesome people that will be happy to give you advice, review your content, and help you grow.

In conclusion

When I started writing this article, I carefully drew an outline, named the chapters and sections, and planned on how to proceed. You don’t need that. As a matter of fact, you can get down to writing something right now, and you might find yourself inspired just because you are doing what you really wanted to do (forget about this article for a moment - it is never guaranteed that it will in fact help you, I am just trying to do my best).

Now my personal goal for the future is to help people not only write better code, but also start helping others do the same. So I am inviting you to share your ideas for articles, videos, tutorials - or any other content you think you can create and share with others, and I will do my best to give you feedback and help with advice - consider this some sort of a challenge. You can both comment on this article and reach out to me on Twitter - I am available most of the time and will try to provide you with the best suggestions I can. Or go ahead and join This is Learning.

Because I believe that you too can create awesome content.

Discussion (0)

pic
Editor guide