How Reading More Technical Content Can Help You Write Better
One of the parting pieces of advice I give in The Developer's Guide to Content Creation is the recommendation to read a lot of technical content. Reading technical content is every bit as important as learning to write because reading critically can give developers tools they can apply to their own work. We can all describe why we don’t like a particular article or video. But how can we use the same level of discernment to analyze something we do like?
In "7 Common Marketing Mistakes Developers Make and How to Avoid Them", I recommend studying how other developers and companies approach marketing. This includes any kind of technical content you can think of, like product documentation, open-source documentation, and company engineering blogs.
Reading more technical content not only enriches your own learning. It gives you different perspectives and shows you the many possible ways you can create content effectively while preserving your own unique voice. There is no single “right” way of producing high-quality content that people enjoy. Reading content from a variety of sources will inspire you to adopt creative approaches in your own work, including developer blogs and eBooks
Here are some questions you should ask yourself whenever you go through a piece of content you really like:
Why do you like a piece of technical content? In 2017, I conducted a survey of Ruby developers who used Bundler. The last question in the survey asked respondents to share examples of open source projects that had good documentation. I asked them what they liked about it. Here are some responses:
“Elixir docs are amazing. I love the embedded examples and details, and links to Erlang docs.”
“jekyllrb.com (docs are split into sections and have Notes, Tips & Warnings and most importantly CODE SAMPLES!!). The KEY point is to have a code example with resulting output (for reference) helps understanding what code does much faster.”
”Both Rails' and Ember's guides do a good job of explaining the concepts used by the framework, as distinct from their specific APIs.”
These developers listed a few characteristics of good open-source documentation. I used these responses to identify and select open-source projects to analyze. I conducted a competitive analysis to see what each project did really well, and narrowed down a list of recommendations for Bundler’s docs that would improve discoverability. (I wrote about the audit I did on the Bundler site and how I used the survey to improve the docs pages.)
Who is their intended audience? If you had to guess who the intended reader is, what they know, what they do, what would you say? Do you believe the content is successful at reaching this audience? If so, why?
What does this (company/individual) do really well? Let’s say you subscribe to an email newsletter that you can’t wait to read each week. What is the thing that keeps you subscribe? Do you like the kinds of articles they highlight or their use of humor? Do they do something you’ve never seen in another newsletter? Good content creators do at least one thing really well that sets them apart from the rest.
What does this content help me do? At the end of the day, technical content is not about the person who created it; it’s about the person who is using it. Good content will help you achieve something, whether it’s learning a new skill, understanding a new topic, or building something from scratch. What does this content help you accomplish? And how does it make you feel? Is it frustrating to follow? Do you enjoy reading it?
How would doing (or implementing) "X" improve my content? It’s not unusual to adopt something we see someone else do that we like: “I like the way Sasha opens up her email newsletters with a tech tip; I’m going to do something similar!” But we do so in the hopes that it will help us improve something. What is your expected outcome? In the above example, maybe you expect that by adding a tip to your own newsletter, more people will click on links in your email, or more people will subscribe. What do you predict might happen? Is this the outcome you want, or do you actually want to achieve something else?
Now that you’ve looked at this content from a point of view of what makes it successful, look at it with a more critical lens. What can they improve upon to make this content even more effective? The perfect blog or newsletter doesn’t exist. But content can (and does) improve over time.
Here’s an example using a company that creates great content: Mode Analytics.
“The company Mode Analytics produces free SQL tutorials. The tutorials are broken up into beginner, intermediate, and advanced. Each level focuses on specific commands, and each section includes examples and exercises.
The tutorials are very well written. I loved following along; the beginner tutorial had really good pacing (not too slow, not too fast), they felt complete without being bogged down with too many details, and I felt like I was grasping the concepts well.
One thing that can be improved upon is the pacing of the intermediate tutorial. It felt as if some steps were skipped; whenever I checked my answers against the correct answers, I noticed my responses always left something out but I didn’t understand how they got to the correct answer. The pacing was a lot more difficult to gauge and I felt like I had to refer to outside sources to better identify what the gaps were.”
What attracted me to Mode's tutorials was my desire to learn SQL. Many tutorials teach SQL, but I stuck with Mode's because of the pacing, structure, and examples reinforced my learning without making me feel frustrated. I enjoyed reading their tutorials.
In summary, reading technical content is not only important for sharpening your technical skills, it'll make you a better technical writer. Reading a variety of engineering team blogs, developer blogs, newsletters, docs, articles, and more will expose you to different styles of writing. Reading technical content with a critical eye will help you identify the characteristics that differentiate great content from content of lower quality, which you can, in turn, apply to your own work.
Like this post? Purchase The Developer's Guide to Content Creation for more content-related tips and exercises.