Hello, Welcome. This is the pilot post of my blog, the first article of many that I’m going to post here :)
I decided as the first subject to address the main motivation of the Blog: Transmitting knowledge through writing. This is one of the points that help me to evolve personally and professionally and I’m going to explain why.
Why Every Programmer is a Potential Writer
I like to think that just as the Sumerians in the ancient Mesopotamian civilization (present-day Iraq) revolutionized the way society transmitted knowledge through the invention of writing, programmers are also revolutionizing writing almost like the scribes of our time. With the inevitable insertion of technology in all areas of society, those who are programming are synthesizing in code the problems, solutions, desires and limitations that we are currently living.
“With great power comes great responsibility"
This is not an easy assignment. Whether naming variables, functions, classes, methods, or describing a pull-request, I’m always doing the exercise of transmitting an idea, or I’m reading a code snippet to understand someone else’s idea.
How Clean Code address, as a text that is not clear a code that is not expressive sometimes almost needs a work of paleontology to understand what is happening under the hood.
The ability to write code that: reveals purpose, uses business domain nomenclatures, avoids misinformation, makes significant distinctions, and has searchable names (among many other quality factors) comes with lots of practice and study over years of experience.
Remember that your code should be clear to you and your coworkers. Code is not a diary.
The exercise of putting myself in the shoes of someone who will read and try to interpret helps me find good points for improvement in everything I develop, whether that person is a coworker, friend, teacher, or my future self.
Software development is not just writing code
Programming is a big challenge and requires a lot of technical studies to clearly express your idea using the best resources of a given language. But is programming just coding?
In my opinion, no. Software development is not only about programming, but it is also about understanding the problem outside the computer bits.
To code better you need to have a broad vision about the reason that you’re coding like: the business problem, the stakeholder’s motivation, what value this development is bringing?, etc.
Talking a little bit about set theory, the programmer is at the intersection between the concrete world of business and the abstract world of software implementations.
Part of my job as a software developer is to transmit the ideas that round development in a clear and concrete way to all stakeholders. The problem understanding and good communication optimize the required effort by everyone involved.
How can I improve my writing skill?
Often as a developer, I need to synthesize complex and abstract content into concrete and palpable concepts. How to explain it?
Visual Elements and Analogies> Buzzwords
In general software developers have their own dialect full of acronyms such as: Docker, Kubernetes, Git, Deploy, ETL, among many others. This communication is extremely efficient among the initiates of that language but it is extremely complex for those who are not. It is very important to know who your target audience is and if they are familiar with these terms.
Analogies are a great alternative to help materialize complex concepts. They are extremely effective in familiarizing strange terms by opening a parallel with something in the person’s reality.
Talking about costs, cloud computing is like connecting to a central power grid instead of producing my own energy. I just need to pay for what I consume and I don't worry directly about how the energy is being distributed
Visual elements like diagrams are a very powerful tool for presenting complex ideas in an agnostic way of technology. Some solutions like Miro provide a wide range of diagrams and tools to make an interactive presentation.
As incredible as your text seems, it's very important to ask for feedback to ensure that your idea was well understood.
Reading
This is the best tip I can give to someone who wants to write well: Read a lot!
Reading books and articles from different subjects gives to me a lot of intellectual input to transmit ideas with different approaches. I usually try to add to my utility belt every analogy or example that makes me understand some concept.
Writing well is even more valuable in distributed teams
In times of remote work in which we have distributed teams, there is a natural tendency for many meetings to align assignments and expectations, especially in places where remote work was far from being a reality.
Without face-to-face contact we lose some elements of communication such as body language, but at the same time we have more opportunities to improve our written communication. A very concise text can save you from long meetings, long contextualizations and can save a lot of your focus time in the day.
Briefly writing the description of the meeting for the participants or stressing some issues/hypotheses asynchronously for an eventual meeting to be more productive has been very effective for me.
Writing better = coding better
I realize that as I’m trying to improve my writing skill I’m also improving my ability to deliver software and solve problems. The exercise of writing and reading increasingly enriches my mental map of how to develop solutions, whether coding or understanding problems.
Not all writing needs to be in articles, blogs and magazines. you can start at:
- In your team’s communication channels
- Pull-request descriptions
- Commit messages
- In the README of the project you are working on.
A polemic post on twitter
Going Further
I hope you enjoyed this first article because I really enjoyed writing it. I’m leaving here some interesting links that I’ve used as a basis for this article.
See you later o/