Writing is a powerful tool that can greatly benefit software engineers in many ways. It helps you to develop and organize ideas, improve grammar and vocabulary skills, and level up in your professional career.

People knew my work through writing. Back in 2018, the goal was just for me to share something out there. However, I quickly realized that writing was not only a way for me to share my knowledge and insights, but also a valuable tool for my own professional career.

Since then, I became a paid guest author for tech publications, won a few technical writing contests, and was also invited to speak at conferences and events.

I found my interest in writing by accident while composing my thoughts before coming into the next design meeting I knew nothing about. I tried to wrap my head around the topic prior to the call, sufficient enough that I could ask meaningful questions or make a contribution. Since then, writing has become an integral part of me as a software engineer.

When it comes to organizing thoughts, I found Richard Feynman’s technique comes in handy, especially when I try to learn new things and write about something. I admire Richard Feynman’s teaching and the way he simplifies complex ideas. His technique is helpful whenever I encounter writer’s block or am in need of a structure to compose my thoughts.

Applying Richard Feynman’s technique in writing is to:

  1. Select a concept to learn - write something you’re passionate about or you don’t know yet but want to write about

  2. Teach it to yourself or to someone else - try to write what you know about the topic

  3. Return to the source material if you get stuck - identify what you don’t know, read more about it, and write what you know about now

  4. Simplify your ideas - write and explain simply for your readers

If you will work on a new and complex feature that needs feedback before implementation, you can write a good design doc. This will help you align your team towards a common goal and resolve disagreements prior to development. You can use Notion and Google Docs to write and gather feedback.

Here are the 3 sections I find important to be in a design doc:

  1. The Problem - aim to describe the problem within the first few words or sentences

  2. The Solution/s - provide the solution that can help your team move forward, and outline some alternatives based on your research

  3. Action Items - this section should answer the questions of what’s next and the estimated time of delivery

I published a couple of internal team wiki pages and design docs that helped my teams onboard new engineers faster and gather feedback asynchronously.

Set up your team’s wiki pages if you think your team lacks documentation around processes, projects, and tooling or if you think you always need to present trivial details during onboarding or technical calls.

The goal is to create a second brain for you or your team, arrive at the meetings prepared, and have meaningful discussions — saving you all a lot of time_._

Here are some documents you can write about:

  1. Engineering Onboarding wiki pages

  2. README files for your projects and team repositories

  3. Design docs for features built

  4. Development workflow and processes

  5. Runbooks and playbooks

Should you write? I recommend trying it out. The learning and skills that you will build through writing are invaluable. Writing allows you to think deeply and care about your readers. By leveraging writing, you can enhance your ability to communicate effectively with your colleagues, clients, and stakeholders.

Leverage grammar tools and AI. There are various AI tools available, such as Grammarly and QuillBot, that can help improve your writing skills and make the process more efficient. But, do not use AI to completely write for you, it defeats the purpose of creating invaluable skills and personal growth through writing.

Over to you: Do you find value in reading technical articles or documents or have you found yourself interested in writing one?

Thanks,
Joshua de Guzman