I recently went through the topics in the DEV Community and found an excellent article on some tips for people who want to start authoring technical articles. So, I decided to write one with my own opinion on the subject and reference some parts of this incredible content.
Some of the following tips and references will be copied from this article for practical purposes only, to prevent the reader from having to search for content in the original article. However, opinions about it are my own.
Why Should I Write?
Everyone, whether they are programmers or not, should write about what they do and what they are learning, or else write only about the life they are leading.
An interesting point that is put in the article is something that we don't think about much. Whenever we read technical content on the Internet, we associate the creator of that content as being an authority or at least having a certain authority on the subject, and that is something extremely positive for your career and also for you as a person.
Being associated with subject matter experts is always good practice. When people read your article on the Internet, they recognise you as a professional and trust you more.
- Extracted from reference
And this is, among others, one of the points why you, as a developer, should start writing technical content, consolidating your status as a development professional can help you in your future career and also influences the way you deal with situations. Someone who is always writing gains important skills for the job market:
- It increases your spoken and written resourcefulness: therefore, it improves the way you deal with clients and other colleagues, in addition, it helps you to create and present arguments in a more clear and concise way.
- It makes you have a new way of thinking: The process of creating articles is something very elaborate, as we will talk about later, it requires that you have an organization and a concrete form of construction, you will not be able to write something if simply throw your ideas in the air. Thinking about writing is a fantastic way to start seeing the world differently
- Prepares you for feedbacks: When we expose ourselves on the Internet, we are subject to all kinds of responses, good or bad, and it is important to know how to deal with both. This allows us to develop the ability to respond critically and deal with compliments in a humble way.
We have already talked a lot about what writing develops as a skill, but beyond that, why should we start writing?
Consolidates Learning
You have probably heard the phrase, "Only those who teach others are really learning", or any of its variations, right?
This is real. Teaching someone else forces you to seek correlations and consolidate your knowledge. A very simple way to do this is to write about it.
Writing makes you need to think about the simplest and easiest way to make the reader understand the content you want to pass, it helps to consolidate your experience and your knowledge in a simple and quick way.
Or, if you are like me, your motivation for writing articles may come simply from the desire to share knowledge with others and to want to observe and analyse points of view and opinions different from yours.
Shines a Light on You
As a professional, it is important for other people to know what you are doing and how you excel at it, what do you want people to know about you? If you have a dream to start working at a company but do not know how to achieve this dream, one of the options is to be more "public", after all, all companies are composed of people and they need to know that you exist.
In addition to a professional advantage, writing also invariably places you on a level of people who, in the eyes of others, become references on what they are talking about, as many will seek their content to complete schoolwork or even create personal projects.
I, until today, remember that, in 2010, when I was starting to learn how to program and, more often than not, I fell on the site of the great José Carlos Macoratti - at the time, I was programming in .NET - and, until today, he is one of my biggest references, even though I haven't touched a C# code in almost ten years. Remember Isaac Newton's iconic phrase:
If I have seen further it is by standing on the shoulders of Giants.
– Sir Isaac Newton
You may be one of the giants where other giants have relied on to develop their creations, you will probably never know that, but other people will - maybe that HR manager at that company where you want to work so badly!
It Captures your Thoughts
Last, but not least, writing creates a repository of knowledge that can be the difference between the success or failure of a project. You do not need to write with the aim of becoming famous, but to register your knowledge for yourself, creating an archive of useful information that you can search for when you need it.
A personal example - which has saved me more than once - is my notes repository, a simple place that, for more than three years, I have written all my learnings from practically all the courses I have ever taken in my life. There are sample repositories, tips and tricks, ideas, and even entire lecture plans.
Writing about something publicly - or even privately - makes you register and have a written mental documentation of that moment, think of it as a snapshot of your brain at a given time.
Why Most Devs don't Write?
We are devs, we are not journalists or reporters, let alone professional writers. Everything conspires so that the dev never writes anything. Among the biggest problems for writing, we have some more pressing than others:
- Shyness: Devs are naturally introverted people - this is often the reason why we choose the profession, machines are much simpler to deal with than people - and this has a strong impact on expression for the whole world through the Internet, but this can be overcome, a very cool example is the article by Mariane Santana, who had never written before and is now on the list of the 7 most read articles from DEV Community 🤘
- Planning: Devs usually have high anxiety, but there is no point in wanting to write everything at once, we need to have a plan
- Lack of practice: Unfortunately, here we can't change much except saying practice makes perfect ... You will only be able to write better if you practice writing more and more. Reading also helps a lot to increase your writing vocabulary and improve the way you write
- Fear of being criticised: As I mentioned, when we expose ourselves on the Internet, we are subject to all kinds of criticism. So, many people simply don't write out of fear of being harshly criticised. In this case, we don't have much to do, just be fully aware of what you're writing and feel ready to answer questions - not interacting is also an option.
The Guide I Wish I Had When I Started Writing
Below, I'll write a bit about some techniques I've learned along all the years I've been writing technical articles. This is the guide I wish I had when I started writing more than three years ago.
Define a Subject
You can write literally about anything. How about your experience using a tool? Or your learning process? Perhaps about how your study of music has influenced your life as a dev. Anyway, you choose!
No one will expect you to write about something that is outside your area of expertise, let alone that you are the ultimate reference in something you are learning (as long as you make it clear that you are learning), you may be uncomfortable with it, but on the other hand, having a perspective on how YOU do things and how YOUR routine is can help other people understand how to be better.
Points of view are always important...
Other writing ideas:
- Own experiences on any subject
- News about your favorite technologies
- Life stories, yours, or others
- Learnings, failures, successes, and lessons you had on your journey
Research, then Plan
A particularly key step in technical writing is the search. You probably won't be the first to write about something. But do some research before you start writing your topic. Also have a plan for what you are going to write:
- Schedule your articles: As I said on my article about personal organisation, everything needs to become a planned task, and with articles it would be no different, plan your dates in advance
- Know about your topic: Know in advance what you want to write about
- Plan your content: Write an outline of your article anywhere, with the main titles and topics
See if there are other articles with the same theme. It is okay to author articles about the same thing - the same as I am doing here - just make sure it is not plagiarism and always leave references to the original content. Here are some options:
- Your personal experience on the topic
- A different opinion
- An addendum to the topic (like this article)
- Translation into another language (always crediting the original author)
Look for as many different points of view on the same topic as possible, the more opinions you incorporate, the richer your article will become.
Give it a name
The title of your article is what will make people interested in reading it. So, it needs to be well thought out. The title must be clear, concise and must indicate the purpose of the article. I will use some of the articles quotes in the reference text:
- Roundup # 58: Orleans 3.0, Snitch, What's wrong with you? Next 5 years of ASP.NET Core
- The Programming Language to Rule them All
- Suffering from Technical Debit?
See why these examples are bad:
- Too many keywords, too much going on, the title is too long, and it seems to talk about absolutely everything
- Very “esoteric”, it clearly looks like a clickbait, but it doesn't give much to understand what the material talks about (this also applies to 3)
- A question to the reader as a title is not a good title. It generates doubt and it generates expectation of response, if the answer you give does not satisfy the reader, then you have just tarnished your reputation for that specific person.
Now for some good examples:
- Career in Programming and Music: What have I learned from all this?
- Developing a CRUD Node.js Application with PostgreSQL
- Tutorial: Data pipeline used MongoDB and Kafka Connect on Kubernetes
See that Ana's article on music contains a question, but it is not directed at the reader, but rather a rhetorical question that refers to herself, explaining what the article is about.
Structure
All articles follow a line of reasoning, this is something we learned at school. All essays must have:
- Title
- Introduction
- Development (This is where we put the code, images, examples)
- Conclusion
- References
With technical articles it is no different, the only thing that will be a little different is the references section that is generally used as a section where you can link an article to the rest of your work.
Time
A Data Lab article showed that the ideal time for an article is seven to ten minutes. This is not a rule, but it does help guide you to how long your content should be. I use an extension for VSCode that shows me this information.
But there is no problem in passing this time if you are writing a more detailed article or a tutorial, after all, it is your content. Just consider the possibility of breaking it into more than one, forming a series, as I do with many of my articles.
Content
People expect to read the content you are saying will pass. Avoid using overly complex words or writing as if it were a scientific article - unless, of course, this is your intention.
Include images whenever possible, gists and use Carbon or CodePen to include code snippets.
Some other content tips:
- Avoid being completely informal, but also avoid being too formal
- Test apps like Grammarly (if you're writing in English) or Microsoft Editor, trust text analytics extensions
- Always proofread your text before publishing
- See if someone else can read the text so it can be revised
- Expand acronyms when they are first used in the article, for example: “Using AKS (Azure Kubernetes Service) …”
- Prefer to use the first-person plural when authoring articles - unless it is an opinion article - because "we" creates a sense of collectivity with the reader
- Don't write long paragraphs
- Whenever you provide data (numbers, etc.), quote the date and source which they came from
Keywords
Keywords are important because search engines will index your text through them. To search for which tags you can use, see some direct examples from the article I referenced:
- moz.com
- app.neilpatel.com
- trends.google.com
- keywordtool.io
- wordtracker.com/scout
Use at least five tags to indicate what you are writing, in decreasing level from most generic to most specific, for example: open-source, back-end, javascript, node.js, cli.
Sharing and Publicity
Don't be afraid to publicize your work as much as possible, use tools like Buffer, Hootsuite and others to manage your most used social networks, schedule your posts. Make use of groups on social networks that are specialised in what you are writing, your audience is there.
Tip: Keep recurring posts about your article, but avoid duplicating the text, many social networking algorithms identify duplicated posts in the same account as spam.
Wrapping up
I tried my best to expose what I have learned by authoring technical articles in recent years. I hope that, with these tips, you will also be inspired to write more and share your content.
Be sure to follow more of my content on my blog and subscribe to the newsletter to receive weekly news! – The content is Portuguese only (at least for now :)
If you want to start writing, but don't know if your article is good and want a second look or you already write and want to share, send me your content through my social networks, I would love to take a look!
You can find them all on my website: https://lsantos.dev
See ya!
Top comments (4)
Great article :)
I am struggling to start writing. Your article is very encouraging. Thanks!
Thx for writing this really inspiring article. I got many nice ideas out of it.
Thanks a lot for the words! I hope you liked it! :D
Authoring technical articles should absolutely not be done for clout, and I feel like I see far too much of that on the blogosphere these days (although, it's hard to tell people's intentions).