Photo by Glenn Carstens-Peters on Unsplash
Summary
Recently, I was browsing through topics on the DEV Community and found anexcellent article with tips for people who want to start writing technical articles. So, I decided to write an article with my own opinion on the subject and reference some parts of this sensational content.
Some of the tips and references below will be copied from this article only for practical purposes, to avoid the reader from having to search for the content in the original article. However, the opinions about it are my own.
Why write?
Everyone, either programmers or not, should write about what they do and what they are learning, or write only about the life they are living.
An interesting point raised in the article is something we don't think much about. Whenever we read technical content on the internet, we associate the creator of that content as an authority or at least having some authority on the subject, and that is extremely positive for your career and for you as an individual.
Being associated with experts in the subject is always a good practice. When people read your article on the internet, they recognize you as a professional and trust more in your speeches."
-Extracted from reference.
So, this is, among others, one of the reasons why you, as a developer, should start writing technical content, the consolidation of your status as a development professional can help you in your future career and it also influences the way you deal with situations. Someone who is always writing develops important skills for the job market:
- Increases your spoken and written fluency: therefore, improving your way of dealing with clients and other colleagues. In addition, helps you create and expose arguments more clearly and concisely.
- Makes you have a new way of thinking: The process of creating articles is something quite elaborate, as we will talk more about later, it requires you to have organization and a concrete construction form, you will not be able to write something if you simply throw your ideas out there. Thinking about the writing form is a great way to start seeing the world from a different perspective.
- Prepares you for feedback: When we expose ourselves on the internet, we are subject to all kinds of responses, either good or bad, and we must know how to deal with both. This makes us develop the ability to know how to respond to criticism in a measured way and deal with compliments humbly.
We have talked a lot about what writing develops as a skill, but, besides that, why should we start writing?
Consolidates your learning
You have probably heard the phrase: "You only truly learn when you teach somebody else", or one 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 by writing about it.
Writing makes you think about the simplest and easiest way to make the person who is reading understand the content you want to convey; this helps to consolidate your experience and knowledge in a simple and fast way.
Or, if you're like me, your motivation for writing articles may simply come from the desire to share knowledge with others and to observe and analyze different points of view and opinions from your own.
Shows you to the world
As a professional, other people must know what you are doing and how you stand out in it, what do you want people toknow you for? If you dream of starting to work in a company, but you don't know how to achieveit, one of the options isprecisely to appear more , after all, every company is made up of people and they need to know that you exist.is made up of people and they need to know that you exist.
In addition, to a professional advantage, writing also puts you, invariably, in the position of people who, in the eyes of others, become references on what they are talking about, because many will seek your content to complete schoolwork or even create personal projects.
I still remember that, in 2010, when I was starting to learn to program and, more than often, I fell on the website of the great José Carlos Macoratti - at the time, I programmedin .NET - and, to this day, he is one of my biggest references, even though I haven't touched a C# code in nearly ten years. Remember Isaac Newton's iconic phrase:
"If I have seen further, it is by standing on the shoulders of giants."
-Isaac Newton
You can be one of the giants thatother giants have relied on to develop their creations, you probably will never knowthis, but otherpeople - perhaps that HR person inthe company where you want towork so much - will!
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 don't need to write with the goal of becoming famous, but to record your knowledge for yourself, creating an archive of useful information that you can refer to when you need it.
A personal example - which has saved me more than once - is my notes repository, a simple place where, for more than three years, I have been writing all my learnings from practically every course I have taken in my life. In there ,I have repositories examples, tips and tricks, ideas, and even my complete lectures plans.
Writing about something publicly - or even privately - makes you register and brings you some written mental documentation of that moment. Think of it as a snapshot of your brain at a certain time.
Why won't developers write?
We are devs, we are not journalists or professional writers. Everything conspires so that the developer never writes anything. Among the biggest problems for devs in writing, we have:
- Shyness: Devs are naturally introverted people - often the reason why we choose the profession, machines are much simpler to deal with than people - and this has a hard impact on expression to a whole world through the internet, but this can be overcome, a very cool example is Mariane Santana's article, who had never written before and is now on the list of the 7 most read articles on the DEV Community🤘
- Planning: Devs usually have high anxiety, but it is no use wanting to write everything at once, we need to have planning.
- Lack of practice: Unfortunately, here we can't change much except to say that practice leads to perfection... You will only 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 criticized: As I mentioned earlier,when we expose ourselves on the internet, we are subject to all kinds of criticism, so many people don't write for fear of being severely criticized. In this case, we don't have much to do, just have full awareness of what you are writing and feel ready to answer questions - not interacting is also an option.
How to write an article
Define a subject.
You can write about literally anything. How about your experience using a tool? Or your learning process? Perhaps about how your music studies influenced your life as a dev? Anyway, you are free to choose!
No one will expect you to write about something that is outside your area of expertise, nor that you are the ultimate reference on something you are learning (as long as you make it clear that you are learning). You may feel uncomfortable with this, but on the other hand, having a perspective on how YOU do things and what YOUR routine is like can help other people understand how to be better. Points of view... always...
Other writing ideas:
- Own experiences on a subject
- News about your favorite technologies
- Life stories -yours or others'-
- Lessons learned, failures, successes, and lessons you have had on your journey
Research and plan
A very important step in technical writing is research. You probably won't be the first to write about something, but research very well before starting to write your topic. Also, have a plan on what you are going to write:
- Schedule your articles: As I talked about in my series on personal organization, everything needs to become a planned task, and with articles, it wouldn't be any different, plan the dates in advance.
- Know your theme: Know in advance what you want to write about.
- Plan your content: Write an outline of your article, with the main titles and topics, in any place.
See if there are other articles on the same subject.
There is no problem in writing articles about the same thing - just like I'm doing here - just make sure it's not plagiarism and always leave references to the original content. Take a look at some options:
- Content from your personal experience on the subject
- A different opinion
- An addendum to the topic (like this article)
- Translation to another language
Look for as many distinct points of view as possible on the same subject, the more opinions you incorporate, the richer your article will be.
Giving it a title
The title of your article is what will make people interested in reading it. So, it needs to be well thought out. The title should be clear and conciseand should indicate the purpose of the article.
I'll use some real examples:
- Roundup #58: Orleans 3.0, Snitch, What's Your Problem? Next 5 Years of ASP.NET Core
- The Programming Language for All Command
- Suffering from Technical Debt?
See why these examples are bad:
- Too many keywords, too much going on, the title is too long, and seems to talk about absolutely everything.
- Too "esoteric," clearly seems like clickbait, but doesn't give much of an idea of what the material is about (this also applies to 3).
- A question to the reader as a title is not a good title. It creates doubt and this brings an expectation of an answer, if the answer you give does not satisfy the reader, then you have just tarnished your reputation for that specific person.
Now, some good examples:
- Career in Programming and Music: What I Learned from All of It?
- Developing a Node.js CRUD Application with PostgreSQL
- Tutorial: Data pipeline using MongoDB and Kafka Connect on Kubernetes
Notice that Ana's article about music contains a question, but it is not directed at the reader, but a rhetorical question that refers to herself, explaining what the article is about.
Structure
The whole article follows a train of thought, this is something we learn in school in our first essays, every text has:
- Title
- Introduction
- Development (Here is where we put the code, images, and examples)
- Conclusion
- References
With technical articles, it's no different, the only thing that will be a little different is the References part, which is generally used as a section where you can link an article to the rest of your work.
Length
A Data Lab article showed that the ideal time for an article is about seven to ten minutes. This is not a rule, but it helps guiding you to the amount of time your content should have. I personally use a VSCodeextension that shows me this information.
However, there is no problem in going beyond this time if you are writing a more detailed article or a tutorial, after all, it is your content. Just take into consideration the ability to break 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 you will provide. Avoid using very complex words or writing as if it were a scientific article - unless, of course, that is your intention.
Include images whenever possible,gists_ _, and use Carbon or CodePen to include codes.
Some other content tips:
- Avoid being completely informal, but also avoid being too formal.
- See apps like Grammarly, and trust text analysis extensions.
- Always review your texts before publishing them.
- See if someone else can read the text so that it can be reviewed.
- Expand acronyms when they are used for the first time in the article, for example: "The use of AKS (Azure Kubernetes Service) ..."
- Prefer to use the first-person plural when writing articles - unless it is an opinion article - because "we" creates a sense of collectivity with the person who reads.
- Don't make paragraphs too long.
- Whenever you provide data (numbers, etc.), cite the date and source of where they came from.
Keywords
- Keywords are important because it is through them that search engines will index your text. To search for which tags you can use, see some direct examples from the reference article I moz.com
- app.neilpatel.com
- trends.google.com
- keywordtool.io
- wordtracker.com/scout
Use at least 5 tags to indicate what you are writing, in decreasing order from more generic to more specific, for example:open-source, back-end, javascript, node.js, cli
Disclosure
Don't be afraid to promote your work as much as possible, use tools like MLabs, Hootsuite , and others to manage your most used social networks, and schedule your posts. Make use of groups on social networks that are specialized in what you are writing, your audience is there.
Tip: Keep recurring posts about your article, but avoid duplicating text, many social media algorithms identify duplicated posts on the same account as spam.
Conclusion
I tried to write simply and conciselyall that I learned from writing technical articles in these last years. I hope that with these tips, you also get inspired to write more and share your content.
Don't forget to follow more of my content on my blog and subscribe to the newsletter to receive weekly news!
If you want to start writing but you don't know if your article is good and want a second look or if you already wrote it and want to share, send me your content through my social networks, I would love to take a look!
You can find all of them on my website: Lucas Santos or on my DevTo
See you!
Top comments (0)