How to Write Technical Articles That People Will Actually Read: An Interview with FreeCode Camp's Chief Editor Abbey

Tips from a Pro on How to Write Clear, Concise, and Engaging Technical Articles/Essays

“Just start writing. This is most certainly not unique or earth-shattering advice, but it’s important.” -Abbey

Writing is an incredibly complex task, and writing about technical concepts is astronomically harder and more complicated. On that note, we did what every hard-core learner would do when faced with a challenge; we sought the input of an expert.

Abbey has been FreeCode Camp’s chief Editor for 6 + years and, as a result, has reviewed thousands of articles with varying levels of technical complexity, which made her the perfect guest to answer our question of “How do you write a great technical article/essay” and on that note, we had Edem go talk to her and see if we could get some tips on how to level up our (and your) writing. The conversation is shared below.

---

Edem: Hey Abbey, It’s great to have you here! Could you tell us about yourself, your professional qualifications, and such?

Abbey: Thanks for including me, Gold! I've been working full-time with freeCodeCamp as our head editor and social media manager (and so on - we're a small team!) for about five and a half years now. I was a volunteer editor for about 8 months before that. 

Before joining the freeCodeCamp team, I was writing a book and a blog, as I was in between jobs - so I got a lot of writing and editing experience doing that.

In my "previous life," I studied Mediterranean archaeology and got to travel all over Europe and the Middle East working on excavations. I also studied Latin, ancient Greek, and several other languages for my university degrees. So I guess the study of words and language has always been part of my academic and adult life.

Edem: Incredible, What role does technical writing play in your daily life?

Abbey: You could say that technical writing plays a very large role in my daily life - but it's mostly other people's writing since I'm an editor. I've read and edited thousands of tutorials at this point on almost any technical topic you can imagine. So there's never a dull moment!

I used to do more writing myself, but I've been quite busy with my editorial and other tasks over the past couple of years, so I write less than I'd like. I think I enjoy editing as much as writing, though, so it works out. There's a certain satisfaction you get from helping other people polish and prepare their work to be released into the world for other people to learn from. You feel part of something bigger.

Edem: Let’s start with something a bit philosophical. How does Technical Writing shape our understanding of technology?

Abbey: How does technical writing shape our understanding of technology - what a great question. I think the way that an author explains a technical concept actually has a significant impact on how readers are able to understand that concept. If a writer uses clear, direct, simple language, chances are the reader will understand what's being taught a lot more easily. This may seem obvious, but it's not always easy to do.

They say that if you can teach something, it means you understand it really well. And I'd add that in order to teach something effectively; you have to understand it inside and out. So if you can explain something to me like I'm 5 (or maybe like 10 for our purposes - let's be realistic here), that's a great sign - and I'm probably going to grasp the nuts and bolts much more easily. Then we can build upon that simple foundation and develop a more complex understanding.

So anyway, a person's writing style is very important. I always encourage authors to write as if they're explaining something to a friend. This keeps the tone straightforward, friendly, and helpful and typically makes the info easier to grasp. This is in contrast to, say, writing an academic paper (for which the style would be quite different, but not always as easy to take in. I used to be in academia, so I think I can say that!).

Edem: That does make sense. How can a good article make a piece of technology more accessible?

Abbey: I'm going to start off by answering this a bit indirectly, but I think you'll see my point in a minute: sometimes, authors write to me asking if they can or should write an article on some (seemingly) basic topic - like functions in JavaScript, or loops in Python - about which many other people have written. They're worried that they won't have anything new to add to the conversation.

But I almost always tell those people to write the article anyway. Because the way that they explain that particular topic might just click with someone, whereas other tutorials didn't.

Now, of course, this isn't as likely to happen if the article isn't high-quality, well-written, clearly explained, and correct. But as long as it's a solid take on a topic, it's going to help someone.

So, to get back to your question - I think a good article is critical for helping learners understand basic concepts. You've probably heard the phrase "tutorial hell" - it's a term I came across many years ago, and freeCodeCamp has actually published articles about it! But if you take a well-written and clearly-explained tutorial and put into practice what you learn from it, you've gone from potential tutorial hell to another, better place. (I don’t know, should we call it “builder’s paradise”...?? :))

The benefit of a good tutorial is that it can explain things in a way documentation might not be able to. There might be that personal touch, that bit of humor from the author, or just a different and perhaps simpler interpretation of how something works. And I think those things are key.

Edem: Let’s get down to the crux of what makes a technical article good. In your years of experience as an editor at FreeCode Camp, you’ve reviewed tons of articles. Is there a sweet spot number of words that makes the most popular articles?

Abbey: I love this question - is there a sweet spot number of words that makes the best or most popular articles? I love it because my answer is no.

It really depends on what you're trying to accomplish with the tutorial. If it's just a quick guide to a particular feature of a language or framework, you might only need a few hundred words. If you're trying to go more in-depth, walk through a project-based tutorial, or teach a more general topic, you might need a few thousand or more. We also publish handbooks and books, which can range from 10,000 words all the way up to 50,000 or more.

My point is this: write just as many words as you need to do your topic justice. No more, no fewer. The tutorial should be as long as it needs to be, in your opinion, to fully cover your subject matter.

Edem: What are the most common mistakes people make when writing articles?

Abbey: Well, there are various types of mistakes writers can make. There is the grammatical/spelling/typo kind, which we all make once in a while. This is where doing some good proofreading can come in really handy. When you're submitting an article to be reviewed by a publication's editor, it's a good practice to make sure you've read through your article a few times to catch as many of those as possible.

Then there are the content-based types of mistakes. Perhaps the writer doesn't understand a topic as well as they should, or they found incorrect information somewhere on the web. Luckily, these are rare, at least for us. The writers I'm fortunate enough to work with are quite diligent in their research and careful in their writing. But every now and then, we catch small things.

So as a writer, I'd just say make sure you do your research, test your code, and don’t share anything with the world unless you’ve proofread, fact-checked, and are overall satisfied with the quality.

Edem: How important is the Title in an article, and how do you get the perfect title considering SEO, relatability, and simplicity?

Abbey: I think the title is quite important - as Quincy likes to say, it’s the only part of your article that basically everyone will definitely read. So it’s important to craft an engaging, informative, and search-friendly title.

Sometimes, I like to think about what someone would be searching for that would land them on this article. That can help you craft a good title.

We tend to stay away from listicles and sensationalist or click-bait titles, as we’re a purely educational publication.

Edem: What separates a good article from a great article?

Abbey: I think many things can separate a good article from a great article. Sometimes a good article is good enough. Does it provide accurate information? Does it help solve a reader’s problem? Does it provide helpful and clear examples? These are all features of good articles.

I think a great article just goes a bit beyond what’s strictly necessary. Perhaps the author writes in a particularly engaging style. Perhaps they add (appropriate and helpful) humor here and there. Perhaps they create their own detailed diagrams and images. These are all features that go above and beyond, in my opinion.

Another way authors can make their drafts stand out - at least for me - is by demonstrating that they’ve thoroughly proofread their articles. This may sound simple, but it’s actually quite difficult to submit a really “clean” article that requires very few edits. But honestly, the fewer edits I have to make, the better. And this is in part because it means that the author took great care to prepare the article for publication (and to potentially be viewed by millions of readers around the world).

Ultimately, our mission is to help people learn how to code for free. So any article that does that effectively is a good article in my book. This doesn’t mean it’s easy to write a truly good article - it just means it’s not magic. It just requires hard work.

Edem: What does a bad technical article look like?

Abbey: I think the most detrimental things to a technical article are a lack of clarity in writing, a lack of explanation of the code or examples, sloppy or hard-to-understand writing, unnecessary complexity, and, of course, factual inaccuracies.

Remember, when you’re writing a technical article, you’re trying to teach someone something. This person may not know anything about your topic. They may know a little. Or they may be a relative expert. But you should try to explain concepts in a way even a beginner can understand (unless you’re specifically writing on an advanced topic or intend your tutorial to be for more advanced developers - which you should state in the article).

If you lose sight of this educational aspect - the goal of the tutorial - then the article becomes much less helpful.

Edem: How do you make articles more engaging and readable?

Abbey: Well, freeCodeCamp has a style guide that’s dedicated to helping authors write really clear, readable, engaging tutorials. So the tips in there should be really helpful.

Some general things to keep in mind: don’t write super long and complex sentences (or paragraphs). They’re hard to read. Don’t overuse formatting. Keep things simple and straightforward. Try to let your personality shine through in your writing a little if you can (and want to do that). It’s nice to “hear someone’s voice” when you’re reading their tutorial. Things like that.

Edem: Technical Articles are mostly about really complex concepts. What is the best approach to introducing really complex concepts to readers without making it boring and losing any of the core required complexity?

Abbey: I do believe that if you truly understand something, you can probably explain it in a way beginners would understand. I think one of the hardest things for more experienced devs to remember is that a topic they consider easy may not be easy for everyone.

Try to think back to when you were first learning about arrays or Big O notation or loops or [insert any topic here]. How’d you learn about it? What made it click for you? What do you think people should know about this topic to really help them understand the nuts and bolts and how it really works?

It’s ok if a topic is complex. The fun part, and the challenge, is to explain it in a way so that someone who doesn’t know anything about it can get the basic gist of it. Be clear, use short sentences and smaller words, use lots of examples (and explain the code line by line when needed), and again - make sure you understand it really well, first.

And again, it’s always helpful to let readers know whether what you’re writing is a beginner-friendly tutorial, or whether it’s made for someone with a bit more background knowledge. Sometimes a simple prerequisites section along with a basic intro to what you’ll be covering is really helpful.

Edem: What are your thoughts on the future of Technical Writing?

Abbey: I believe it’s important to have many different perspectives on the same topic. As I discussed above, every author will explain x topic a bit differently, and that might be the explanation that clicks for someone. So I think that’s a big benefit that technical writers bring to the educational space: their different experiences, knowledge bases, and perspectives.

It’s hard to say what will happen over the coming years - many people are experimenting with AI tools, and that’s great. But another benefit of technical writing is that it’s a great way to learn a topic really well. So it’s helpful to the author as well as to people who might read their work. I don’t think that’s something we should forget. (Ya know, the actual learning part :).)

Edem: What are some of the best resources to learn how to write Great technical articles?

Abbey: Read a lot of great technical articles! :) This will give you a sense of what works, how other writers explain things effectively (and when it’s not so effective), and how you may want to structure your own tutorials.

I know there are actual resources out there - courses, books, etc - but experience is also key. Just write a lot. Work with an editor. Have a friend read your work and give you comments. Have the desire to get better. Ask people to coach you or give you tips. I’m always happy to review changes with authors or give general feedback, for example.

Edem: Let’s talk about your work at freeCodeCamp a bit. I have no doubt you get a lot of submissions daily, some really lengthy (like mine) and with varying levels of complexity. How are you able to go through them efficiently?

Abbey: It used to take me hours to edit one article. Now I’m pretty quick. I know what to look for, and after almost 6 years of doing this full-time, it comes much more easily to me now.

Some articles take longer than others, depending on the amount of editing I feel I need to do. But I just work through the submissions as best as I’m able. It does help that I enjoy the work, so typically it breezes by.

I also have an editorial team now, so I have help! It’s wonderful to be able to work with editors who are also authors, as they have a great sense of what needs to be changed when something doesn’t make sense, and so on. So that’s super helpful.

Edem: What advice would you give to someone about to begin his or her technical writing journey and wanting to build a niche and career out of it?

Abbey: Just start writing. This is most certainly not unique or earth-shattering advice, but it’s important. The more writing experience you have, and the more you try to improve, the more likely you’ll be able to publish your articles beyond your personal blog.

But start a personal blog - that’s a great place to practice. Write about what you’re learning or about what you want to know about. Write to help others. Publish your articles on tech publications as you’re able. Build up your portfolio. And seek help in improving your writing if you think it needs some work.

Edem: What advice would you give to someone transitioning from full-time engineering or academia who wants to become a writer?

Abbey: I think many careers are great precursors to becoming a technical writer. If you were an engineer who’s looking to get into writing, use your knowledge to write great technical articles and show what you know. If you were in academia, chances are you’ve done a lot of writing already. Just adapt your style to be a bit more approachable and less formal.

Just use the skills you already have and apply them to writing. Many of the skills we build up in our careers are transferable - we just sometimes have to be creative about it.

Edem: Thank you very much for your time Abbey. It was incredible! Any closing words?

Abbey: Thanks for asking me to share my thoughts! I really enjoy working with all the wonderful, intelligent, kind authors that I get to work with as part of my job at freeCodeCamp. It’s a pleasure to help them share their knowledge freely with the world, and I’m grateful to them for it.

So go forth and write! Share what you know. It helps make the world a better place.

---

Leave us a comment if you have a question for Abbey and we’ll pass it through.

And remember you can share this newsletter and get cool rewards.