Writing as software engineer
How to become a better writer as a software engineer.
Hi Friends,
Welcome to the 100th issue of the Polymathic Engineer newsletter.
To celebrate this milestone, we discuss a skill that will become more and more important as you progress in your career as a software engineer: writing.
Building up writing skills takes time, but they become a superpower when you combine them with technical skills. In this issue, I will present you with a framework you can use to become a better writer and try to give you some good advice.
The outline will be as follows:
Why writing is important for a software engineer
Writing the first draft
Editing
Getting feedback
How to become a better writer
Project-based learning is the best way to develop technical skills. CodeCrafters is an excellent platform for practicing exciting projects, such as building your version of Redis, Kafka, HTTP server, SQLLite, or Git from scratch.
Sign up, and become a better software engineer.
Why writing is important for a software engineer
Writing is an essential skill for software engineers but is often underrated. Indeed, a lot of engineers don't realize how much it affects their professional growth and ability to collaborate with others.
To dispel the myth, I will start by mentioning why I think improving your writing skills is essential. First, as a software engineer, you spend more time writing words than writing code.
You write every day in chat messages, emails, planning documents, technical reports, code review comments, among other things.
Clear writing helps you get your ideas across quickly, reduces misunderstandings and puts you and others on the same page. That's especially important in distributed teams, where face-to-face communication is limited, and writing is the primary mode of communication.
Another thing is that writing lets you share your knowledge and ideas with the tech community. Sharing your expertise through blog posts or technical articles not only helps others and positions you as an expert in your field but also reinforces your understanding.
Writing about complex technical problems and their solutions makes your problem-solving skills better. You can often find different ways to solve a problem or ideas if you break it down and explain it in more detail.
Finally, being able to write well can set you apart in the job market. Producing well-written documentation, proposals, and reports is a valuable asset. It shows that you pay attention to details, think clearly, and can communicate effectively, which are very important in lead roles and more senior technical roles.
In the following subsection, I'll go through a process you can follow to write better content. Applying it to everything you write is unrealistic, but it makes sense to use it whenever the content is important or direct to a broader audience.
Writing the first draft
A well-written piece of content requires several steps behind the scenes. Writing the first draft is the initial step. Even if the draft should only capture most of the ideas and content, many engineers get stuck at this point.
The first thing to understand is that your first draft won’t be perfect. However, that’s okay since the goal is to get your thoughts down. Editing and refinement come later.
Another helpful thing is to divide your writing task into smaller sections.
Instead of thinking of writing a complete document or posting in one go, start with an outline. Break the content into smaller chunks and address each part individually.
This approach reduces the feeling of being overwhelmed and makes the process more manageable.
It’s also important to allocate a specific time to write without interruption. It helps you to stay focused and maintain momentum. During this time, concentrate solely on writing without allowing distractions.
Editing
Editing is the most crucial step in the process since it turns your rough draft into a polished and logical piece of writing.
When you're ready to edit, start reading your draft to get an overall sense of the flow and structure. Pay attention to whether your ideas are logically organized and whether each section transitions smoothly to the next.
If necessary, break the paragraphs into smaller pieces that are easier to read. Ideally, each paragraph should contain only a few sentences and convey one thought. The Hemingway Editor is a good tool for understanding which parts can be broken down.
Next, focus on clarity and conciseness. Try to put yourself in the reader's shoes and see if your writing is clear and straightforward. The principle should always be to value the time of your reader more than yours.
Avoid unnecessary jargon or overly complex sentences. Each sentence should serve a purpose and contribute to your overall message. If you find any redundant or irrelevant content, remove it to keep the reader engaged.
Another good way to simplify a piece of content is to use bullet points or numbering where they make sense. They can help to list related items in a way that's easier for the reader to go through than writing paragraphs.
Finally, look out for grammar and punctuation errors. These can distract the reader and undermine the professionalism of your writing. I strongly recommend the use of Grammarly or similar tools to catch common mistakes.
Getting Feedback
If you’re writing technical documents or a blog post, the last crucial step is obtaining feedback.
Feedback provides an external perspective that can highlight aspects of your writing you might have missed. Ideally, choose reviewers who understand the subject well and can provide constructive criticism. Colleagues or mentors are often a good choice.
However, when you ask for feedback, be specific about what you need. Are you looking for comments on the technical accuracy, overall structure, readability, or tone?
Providing guidance helps reviewers focus on the areas that matter most to you.
How to become a better writer
Becoming a better writer is a journey that involves consistent practice, learning, and refinement.
Here I put together some advice to help you improve your writing skills:
Read Regularly: Reading a variety of documentation, articles, books, and blogs, exposes you to different writing styles and techniques. Pay attention to how other writers structure their content, explain complex concepts, and engage audience.
Write Daily: Make writing a regular habit. Even if it's just a few sentences or a short paragraph each day, consistent practice helps you develop your skills over time. The more you write, the more comfortable and proficient you will become.
Engage Your Audience: Tailor your writing to your audience. Consider their level of knowledge and what they need to take away from your writing.
Use visuals: Add pictures, charts, and diagrams to your text to help people understand it better. With technical documents, a good visual is often worth a thousand words.
A couple of good books that will help you write better and more concisely are On Writing Well and Dreyer's English: An Utterly Correct Guide to Clarity and Style Hardcover.
Thanks for this ⭐! Writing was one of my biggest challenges at the beginning of my career as a software engineer. I’d spend so much time reworking emails or documentation to make them clear. With practice, though, it’s become one of my favorite skills.
Through writing, you improve your way of thinking. You put your thoughts in order. It's a great way to enhance your communication skills. Great article, Fernando! And thank you so much for the mention!