5 Steps to Writing Your Next Technical Article
Originally published at pagekey.io.
Over the past few months, I’ve written a fair number of technical articles (here). At first, it felt unnatural to apply what I learned in English class to the cold logic of programming and computers. Despite this, I rinsed and repeated enough times to see that it’s not such a bad fit after all. Below, I outline the five steps I take, in one form or another, every time I write a technically-focused article.
1. Research and Take Notes (Do the Thing)
As you write your article, you’ll take on the role of teacher. In doing so, you’ll get to experience the highest form of learning, and will probably discover at least one thing about what you’re writing that you didn’t know before.
Before you can be the teacher, you have to do the thing, whatever that thing may be. I’m reminded of an oft-cited Emerson quote:
“Do the thing and you will have the power.”
Ralph Waldo Emerson
Regardless of what your tutorial or topic entails, be sure to experience the entire process, start to finish, at your own pace. If there’s no step-by-step process involved, now is the time to look up answers to questions you may have about the concepts, or even ask new ones that you may not have thought of before. Your audience will have more questions than you could possibly think up in one sitting, but you can do your best to cover the majority!
As you go through this process, please take notes. Every button click, every prompt, everything you type — write it all down. When you’re trying to reconstruct exactly what happened for someone else’s consumption, you’re not going to want to dive back into the level of detail necessary at the research stage. Save yourself the trouble and document the details now.
2. Create Outline from Notes
The value of a good design can’t be understated. Now that you’ve researched and taken notes on the process from start to finish, look over your notes and start putting them in a logical order, if they’re not already. Form a bulleted outline for your article that lists each point or step, along with the details and caveats that go with each. When you have a detailed outline with all of the hard facts you need in one place, actually doing the writing will be a cinch.
Speaking of which…
3. Write the Article
The time has finally come. Put on some warm socks, sit down at your desk, and get comfy — it’s time to write!
Hopefully, you have all of the information you need to get your writing done. Don’t be afraid to add onto your outline or notes if you discover something missing, though. There are always new questions to be asked, regardless of what step of the process you’re on.
Some people may feel a lot of pressure during this part of the process. This is your time to make it happen! It has to be good! What should I even write? I have to erase that sentence. And that one. I can’t even get started here.
Don’t be like that. If you have to, set a timer for 20 minutes, and just write. Don’t worry about spelling, grammar, or anything else. Listen to the voice in your head speak about the topics in your outline, and just write it down, like you’re copying down a speech. All of those important details can be ironed out in the next step.
If you’re really having trouble, another little rule you can use is to not erase anything during this stage. Remove the backspace key from your keyboard if you have to (at your own risk — I’m not liable). If you’re too self critical, you may end up erasing some important ideas as you go along. Even if they’re in rough form, they’re still valuable.
4. Revise
The article is written! Hurrah!
So you’re done, right? Time to pack it in?
Not so fast, pal. The most important job is still coming. Don’t turn your brain off just yet.
The task of revising is perhaps the most essential part of the writing process. Once you’ve written the basics and gotten something down on paper, good or not, you’ll find plenty of updates to be made by reading through the article with a clear head and putting yourself in the shoes of your readers.
You may want to edit immediately, but more than likely you’ll need a break between writing the article and editing the article. At the very least, go get a cup of coffee or tea. At most, give it a day to percolate in your head before going back to the editor’s desk. Don’t wait too long, though — you want the details of what you’ve written and what you’re trying to express to remain fresh in your mind. It just doesn’t need to be so fresh that you can’t see it from any other perspective.
Several passes of editing may be a good idea, because with each readthrough, you’ll find new things to add or change. Don’t get too bogged down though. If you’re doubting yourself or your writing, push through it and proceed to the final and most essential step: Shipping.
5. Publish
If you don’t publish your work, you’ll be letting all of your hard work in the above steps go to waste. Don’t let that happen. Seth Godin refers to this concept as “shipping” in his book, Linchpin:
“The only purpose of starting is to finish, and while the projects we do are never really finished, they must ship.”
Seth Godin in Linchpin
Even though your article could probably use a little more polish, a few extra words, or a little more rephrasing, this will always be the case. Be brave — hit the publish button so you can get on to the next article. Even if this one isn’t your best work, you can always improve on it next time.
Next Steps
Try putting this into action! Pick something that you know how to do, run through the steps and this article, and see what happens!
When you try this method out, please let me know. Maybe you’ll discover a few new steps that I didn’t know about. Be sure to share your findings (and your newly published work) in the comments.
Do you enjoy learning about programming and computer engineering? If so, PageKey is the place for you! Click here to visit.
Originally published at pagekey.io.
