While on vacation this week, aside from time spent with my family, I did a few things:

• Read large chunks of the SQLite docs
• Wrote an announcement article for a new open source package
• Edited my upcoming Django book

With each of these things, the audience became obvious to me. And that’s important since an undefined audience is bound to lead to writing that wanders. If you want to learn how to write technical documentation with impact, I think my thoughts below will help.

Without a clear audience in mind, you won’t know the necessary boundaries for your writing.

The audience helps you craft your narrative. Your audience has a set of skills and knowledge as a collective. You must write with that set of skills in mind because you can’t explain the whole world with everything you write.

My son is a fourth grade student this year. One of his electives in our homeschool is programming, taught by yours truly. After months of instruction, it’s true that he is a programmer. As I write my upcoming Django book, do I have my son in mind? No, I don’t. He is not far enough along in his programming journey for my material to make sense to him.

I had to devise a persona of who I’m writing for with my book. Unless my book should be a tome with thousands of pages, it’s unrealistic for me to craft something that teaches “if” statements, “for” loops, and the fundamentals of programming. I have to assume that my audience is coming to my writing with a baseline of knowledge.

There is a tension when dealing with an audience and how much knowledge they have. Since we aren’t all clones of each other, the knowledge of an audience is a range. While some people will already have a strong handle on core concepts, others might be weak. To compound the problem, knowledge is not linear. Each person will have a set of skills, some strong and some weak.

That’s a big part of what makes each of us unique. Your experience is a huge portion of what defines who you are. When I’m thinking of an audience, I have to think in averages. Sometimes I need to over-explain in an area to fill the gaps, but if too much explanation is given, then the message of my writing is lost.

Before I started writing my book, I thought of a few pillars of knowledge that I expect for someone learning Django.

• The person has some base knowledge of how to program.
• The person has some base knowledge of how to program with Python.
• The person has some interest in the web and has dabbled with related web technology like HTML, CSS, or JavaScript.

Without these guidelines, the audience for my book is too big to reach in a reasonable number of pages. While I enjoy teaching my son the fundamentals of programming and explaining how things like variables and loops work, I don’t want to write a book about that.

How does this relate to technical documentation?

Technology and software is surprisingly niche. In my experience, it’s true that you can learn multiple languages rapidly because many of them have common idioms with slight variations of syntax. Even though developers have the capacity to learn multiple languages, it’s generally easier to express ideas when there is a common foundation.

For instance, a few months ago, I learned some Laravel for a presentation that I gave at Python Frederick. I needed enough Laravel experience to demonstrate a frontend technology (htmx) could be used by multiple languages. Even though I know the concepts of web frameworks extremely well by now, the PHP idioms tripped me up at various points of reading the documentation.

As good as the Laravel docs are, I wasn’t the right audience. I started out with PHP when I first learned to program, but that was 20 years ago and my skills with the language are rusty. Because of this skill mismatch with the audience expectation, I think some of the ideas in the Laravel framework bounced off me.

What can you do to set the right audience? The simplest way is to be direct.

Tell readers, at the start of your writing, who your audience is. It doesn’t help to hide your expectations from the people reading your work. You’re going to lose people when you state these expectations, but that’s ok. The people that weren’t right for your material may struggle without the requisite knowledge. The goal of writing is to share knowledge, not make people struggle needlessly. As a benefit of being direct, if someone is not the right fit, you’ll have told them directly what they can do to grow the right skills to go on the journey with your writing.

Be lenient in your writing. Occasionally repeating a concept that you think your audience is likely to know is ok. Too much repetition will lead to bloat, but some repetition reinforces rather than detracts.

Get an editor (or editors) and have them hold you accountable. You’re going to make assumptions about what your audience knows, but sometimes your assumption is too far. The leap is too big. Editors can help you keep the audience in mind. Other people, with their different set of experiences, will have a subtle variation in mind of what your audience means. Where you assume something is obvious or should be known, they might see that as unobtained knowledge for your audience that needs some explanation. The guidance of others can help you steer toward the real audience that your writing is trying to reach.

Find your audience. Your writing will gain a clarity and precision that readers will appreciate.