This marks the first step in my journey of writing up my experience in a way that can contribute to general engineering knowledge. The purpose of this blog is to provide a place where I can decompress my knowledge from my brain and write it down. First and foremost is getting the idea of the blog off the ground.
With that out of the way, let’s get into this article’s topic!
Technical writing is a crucial part of any senior engineer’s skill set, as we must be able to define and describe complex systems so they can be consumable by not only the technical team but also by our supporting financial and business operations teams. This is a skill that I see many IT engineers guilty of not practicing -- myself included. Hence, it is important that, just like our technical skills, we work to write strong, valuable documentation in our free time to keep our writing skills fresh.
Now for the technical reader, you may be wondering, “What is the point of writing documentation just to write documentation?” That’s just it! We’re building personal projects, working in our home labs, or just thinking about improving critical processes at work the next day. Writing these ideas down in a standard format will help them come to fruition. In the worst case, it will provide a springboard for when a project is put on hold. This freeze could last for days, weeks, or even months! Just like leaving meaningful comments in our code, we should have supporting documentation outlining where we left off, what configurations we intend to implement, and a backup of any critical config files that could help us if we break the system as we relearn it. But what should we include in our writing?
I’m sure we’ve all encountered projects on GitHub with lackluster README’s that leave us wondering, “This has features I need, but how do I actually implement it?” Well, that is where our technical writing skills come in. It is important to cover all your projects’ “so what”-s in a manner that a technical contributor can replicate your process. At the bare minimum, we should be detailing prerequisites and dependencies; configuration file items and what they do; links to external resources like API portals; a quick start guide; and any currently known issues or limitations. Being open to sharing this information upfront for your open-source project welcomes contributors of many skill levels who may find the missing link to improving your solution. At the very least, it provides an opportunity outside of work to not create technical debt for a change!
All in all, technical writing is a critical skill for most modern-day professionals. Whether it is to describe business processes, detail data flows, or map out a hybrid cloud environment, being able to express technical details in writing is a valuable hobby to take up.
