Technical writing presents its own unique challenges (and rewards) as an author. It can be unusually difficult for us, as engineers, as we often spend our days communicating with computers through transcribing arcane symbols and stitching together abstract APIs. Sharing our experiences and learnings from these “odd” types of conversations with other human beings isn’t something that comes naturally and that’s OK. It’s a skill that you have to build, like any other.
I believe it’s incredibly important to put yourself out there, share your knowledge, become vulnerable and open to feedback. This post is written for those of us interested in helping others but aren’t sure where to start.
The section titles below map to P.S. as a mnemonic to help you remember them!
Problem Statement
This is an easy, but often overlooked point: clearly state the problem you are trying to (or have successfully) solve(d). If you haven’t figured out how to do it yet, but already learned some invaluable lessons, it’s still worth sharing.
This is your hook for the reader, so be sure to give some background as to why you thought that this problem was interesting enough to tackle. Maybe you didn’t find any other explanations/solutions on the Internet and, having invested considerable time and effort, just want to give back to the community. Or perhaps the other approaches you did find were too convoluted, misguided or downright incorrect and you don’t want others to have to struggle like you did.
Taking the time to explain your motivation gives the reader their first inklings of understanding your thoughts and opinions.
Present Solution
You’ve probably spent untold hours poring over insufficiently documented and unexplained intricacies of the problem at hand. With this knowledge and experience, it’s hard to rewind backwards to that blissful period of ignorance and naivete, but good stories take time to develop.
Be sure and start at the beginning (the problem statement) and the steps you took, both forward and back, towards the end goal. It may seem convoluted or a waste of time to describe in detail the wrong turns and mistakes you made, but these really do help encourage others to:
- Not make the same mistakes
- Improve the product/service so others don’t run into the same road blocks
- Acknowledge your humanity (and spark a connection)
Even trivial solutions should be shared: you might have accidentally solved it in an incredibly elegant way that will baffle others. But, most importantly, the very act of explaining your solution by writing it down in a post helps crystallize the learning. Taking the time to organize and present your findings for others helps you truly “finish” and add that bright green checkmark.
Publish Sources
If at all possible, share your solutions in the form of open source code. From Gitlab to Github, there are all kinds of online source code repositories that champion the hosting and distribution of software applications and infrastructure automations.
Give people access to the nitty gritty cogs, wheels, buttons and levers of your solutions. Let them fork your codebase to improve upon or embark on wildly new, better ideas. It’s a big step putting yourself “out there” and sharing your code with the rest of the world, but it does get easier the more you do it. Remember, taking this step means you’ve been hyper-vigilant with your secrets.
Peer Screening
Focused work on a complex issue sometimes gives us superpowers. We get into a state of “flow” where things don’t need explanation and we feel a “god like” understanding of the topic. Stepping back from these heady heights to impart your wisdom to “mere mortals” is extremely challenging.
Hand over your (most likely) incoherent scrawlings to someone far removed from the topic and get their honest feedback on what you’ve written and how well you’ve conveyed your message. We all inwardly flinch at the term “feedback”, but embracing it can really make the difference between unfathomable tripe and convincing.
Take the time, swallow your pride and rework your text. Having the chance to solicit others’ opinions on your writings is invaluable. Taking the opportunity to clarify your intent before publishing is worth its weight in gold.
Please Start
You miss 100% of the shots you don’t take. The fact that you invested time & effort in pursuing a solution to this problem, means there’s a non-zero chance someone else has/will have the same problem and is/will be looking for a solution. Too often, we finish coding/scripting/building and move onto the next problem without adequately publishing our findings.
It’s lonely out there! I’ve written hundreds of posts since 2007 and very few have gotten meaningful feedback or engagement. Almost a decade ago, I needed to learn how to set up millions of rewrites in nginx. A quick Google search turned up absolutely nothing. Months later, after I figured it out, I wrote the blog post “Supporting Millions of Rewrites with Nginx in Lua and Redis”. To this day, folks still reach out to thank me and that means all the world.
Imagine how difficult our road would be if all the giants, on whose shoulders we stand today, hadn’t published and explained their work to us. Open communication and more transparency on the things that motivate us will only clear the path for those that follow in our footsteps.
Share the love by passing on what you have learned!
Good post! I agree 100% with you. I even started writing my blog with all the things I had to do not very often and always forgot how to do them. Sharing is caring, including your future self! 🙂