My Technical Writing Process
How I write technical posts and hacking tutorials…
Some of the questions I get the most online are “How do I start hacking?” and “How could I write better technical posts?” After the announcement of my book, I also had people asking me what that process entails.
I love technical writing because it’s a way of sharing knowledge. You can share what you’ve learned and expedite the learning process for others without ever meeting them in person. So I encourage most technical folks to give writing a try. It’s a great way to clarify your thoughts, understand a concept more deeply, and participate in indirect mentorship.
My writing process has not always been the same. I started my blog two years ago, and it wasn’t until I started doing it professionally that I settled on something that worked for me. I have established a solid routine that helps me write consistently and efficiently.
In this article, I will share an overview of my process. I hope it will help you gain some insight into how to write technical content and make you give writing a try too.
Research
The first step to writing any technical article, blog post, or book chapter is research. I try to find out everything I can about a topic. I read the documentation about a technology, I read blog posts and write-ups about a technique, and collect as much information about a subject as possible. I make detailed notes during this process and organize the information I found. I also fact-check everything I read about and test out all payloads, code, and exploits to see that they all work.
Outlining
The next step is outlining. And this is probably the most challenging part of the entire process. In this step, I am figuring out what information to include, what not to include, what sequence to introduce concepts in, and what structure of writing would be the best for the information at hand.
This step takes a lot of time and often goes through multiple iterations. And I often find myself changing the outline and structure of an article later in the writing process. For example, for my book Bug Bounty Bootcamp, I had to do a major overhaul of all the chapter outlines six months into writing.
I would argue that this is the most important part of the process (along with research) since this is when you’ll be deciding what you’ll be presenting to the reader and how.
Dumping Words Out
Next, I go through my outline and fill out all the relevant information for each outlined item. I typically have my notes from the research phase by my side. The goal is to translate the concepts I’ve learned there into plain, spoken English.
An important thing to remember at this point is not to edit yourself when writing. Simply capture all your thoughts that you want to express and quit worrying about style and grammar. Those can all come later.
Making Art
If the article requires diagrams or infographics, this is when I make them. There’s not much to say about this process since it’s very much dependent on your personal style. For instance, I prefer hand-drawn graphs over something generated by software like Canva or Google Sheets. I also prefer to inject a bit of playfulness or humor into my graphics. But it all depends on preference.
With that said, all good technical art has one defining trait: Less is more. Don’t try to convey too much in a single JPEG. Distill what is necessary, what will complement your post, and throw out anything else.
Take a Break
Before the editorial stages, I always take a break. I typically schedule my entire writing process into at least two days so that I am not editing my writing from the same day. This helps me look at my article with a fresh set of eyes.
Technical Edit
Once you have your baseline of technical content and all artwork, the next step is to ensure that both the text and images are technically correct and do not contain any mistakes.
Besides blatant technical mistakes, you should also look for technical holes in the content. Is there anything that you failed to explain? Are there any logical jumps? Is there something that could use more explanation or a reference to another resource?
Common Knowledge Edit
The next step is what I call the “common knowledge” edit. In this phase, I try to read my writing as someone else — someone with no prior knowledge about my topic and is instead equipped with the “common knowledge” for my target audience. For instance, for a security code review article for developers, I can assume that my readers already understand the concepts of HTTP, cookies, encryption, etc.
When writing my book, I also assume that readers have read previous chapters, so I can add that knowledge to my “common knowledge.”
Copy Edit, Copy Edit, Copy Edit
By this point, the technical content of your article is fixed. The next thing to do is to refine the words and sentences. Delete the content that doesn’t add meaning or clarity to your article, think of ways of phrasing each sentence better, and review your word choices.
Clean up the language and make sure that the article flows, makes logical sense, and is easy to read.
Grammar Check
Next, I run my article through a grammar checker. This step is essential! Good grammar ensures that your writing will not be misunderstood.
When you first start, don’t be discouraged when your grammar checker finds hundreds of mistakes in one article. Your grammar will improve once you learn good writing habits, which will naturally happen after you write a lot.
Reading Out Loud
Finally, read your article out loud for a final check. Reading an article out loud is the ultimate check to see if your article is easy to read and often uncovers those last inconsistencies and mistakes.
Thanks for reading! Connect with me on Twitter.
You can find my book, Bug Bounty Bootcamp, at Bug Bounty Bootcamp.