Hacker News Reader

I have been a tech writer, and I would say something similar, that you need to know two things to write well: audience and purpose. The road becomes a lot clearer after that. Rules on writing fill whole books, but most writing would improve tenfold if writers remembered audience and purpose.

How do you fumble something so obvious? Selfishness. The poorest writing I've ever come across I have to assume that the writer is not writing primarily for the reader. He's writing for his boss ("My boss told me I have to write documentation. Once I get this done, he'll be off my back."), for his company ("I have to cover every possible shenanigan in this license or my company might get sued"), for his paycheck ("I'm going to pour on euphemisms like maple syrup so the reader can't help but be hynotized into buying our product"), or for his ego ("I'm going to use really big words, fashionable memes, and a chummy style to get people to think I'm smart.").

All of the other sins are microscopic compared to the writing from selfish motive. Most of the other rules fall into place if you remember just this, love thy neighbor as thyself.

>"Know thy audience" is one of those concepts where, the more you think about it, the less you realize you know.

And it's doubly hard because the audience is almost always something of a mix. I've given more than one presentation where the survey has included some variant of both "Way too basic" and "Went way over my head."

Yes, this is a common dilemma. Some suggestions on how to handle in docs:

* Too much information is usually better than too little. You can organize the extra information into separate sections, which makes it easier for the advanced audience to skip over. * Prioritize one audience over the other.

In the case of presentations I'd probably stick to prioritizing one audience over another. Given a room of people, who is it most important to transfer knowledge to? Better to make half the room happy, than none of the room.

It's easier in documentation/writing because people can skim or just quickly decide that what's there isn't for them.

There's more of a commitment in a presentation. It helps to advertise things accurately. Although there's no shortage of people who come to an "Introduction to" talk and expect it to be deep in the weeds.

Agreed, presentations are harder than writing in this respect. Conversely, I think docs are usually more effective than video when it comes technical communication precisely because you can scan them. Generally speaking, it’s just a more flexible mode of communication. Although I’ll add that I do supplement the DevTools tutorials with video versions, because some people prefer to see GUI workflows in action.

It's not hard if the writer deals with their NIH syndrome and realizes that journalism figured this out like 125 years ago with the inverted pyramid structure.

I guess I don't understand what giving a presentation at the right level for an audience has to do with an inverted pyramid structure of a news story. In any case, it's only some journalism. Mostly straight news in newspapers.

And the motivation was partly practical. Inverted pyramid lets an editor cut a story at a more or less arbitrary point in order to fit it in a hole of particular size on a page. This is/was particularly true of wire service copy.

Unless your have required attendance, this phenomenon means you haven’t made it clear beforehand what audience your presentation is intended for.

In my experience a lot of people are very bad at paying attention to what it says about session difficulty in the program. I was on the program committee of a tech conference for a number of years and saw a lot of feedback forms from people who clearly don't understand what words like "introduction" and "deep-dive" (and their numerical equivalents) mean.

We tried a lot of different approaches and you still end up with some audience members whose expectations are seriously out of tune with the content of sessions.

Of course, sometimes there's fault with the presenter too.

This will often be the case, whether for writing technical docs, books, articles or other matter, unless you have a curated or specifically targeted audience. It's one of the occupational hazards of writing.

>I've given more than one presentation where the survey has included some variant of both "Way too basic" and "Went way over my head."

I once gave Unix and C training (two separate courses) to a group of experienced corporate IT developers (at a large Indian public sector company, Hindustan Aeronautics Limited). When I was explaining some of the finer points of pointers (pun not intended), like star star argv (pointers to pointers etc. - in the C course), one of them said: "now it is overhead transmission" :)

> "Know thy audience"

With end users I find it very hard to predict technical knowledge, which can vary by orders of magnitude and often include misinformation or the completely wrong focus, and which users themselves estimate unreliably. For that reason, unless I know better, I tend to aim low - better to tell them extra than to make it incomprehensible.

There seems to be ego tied up in it for users; if you aim to high, they won't admit that they don't understand, and if you aim too low they might get insulted:

I get complaints, often politely implicit, that they feel condescended to. How does one communicate the basics without sounding condescending? I have some sense of it, of course, but I don't feel that I know the trick.

One thing you can do is state assumed knowledge at the start of your documentation. Then you can provide references to other documents in case the reader doesn't know the prerequisites for the doc.

> if you aim to high, they won't admit that they don't understand, and if you aim too low they might get insulted

Yes, it's a tricky balance. Another way to frame the importance of this topic is: if you explain too much, you make your readers wade through a flood of information, which slows them down; if you explain too little, the doc is unusable.

> How does one communicate the basics without sounding condescending?

ASinclair's suggesting of adding a prerequisite section to your doc is a good strategy. It also helps to develop "content types" where you describe in general what types of information you include in each type of content. For example, suppose you define 3 content types: overview, tutorial, and reference.

* The overview contains conceptual explanations.

* The references contain everything you might possibly need to know about a given topic.

* The tutorial contains task-based, step-by-step workflows. Rather than explaining concepts in the tutorial, you link them to the overviews. Rather than going into the nitty-gritty about a topic, you link to the reference.

You probably get the idea from here. Each content type contains clearly-defined amounts and types of information. Rather than jamming all the information into a tutorial, you link off to the overview and reference. The people that need more information can follow the links to learn more. The people that don't need it get a straightforward tutorial without extraneous info.

> The most crucial skill for creating quality documentation is to know your audience

This can be tricky when your audience doesn't have a homogeneous skill level (e.g. people copy-pasting GA snippets don't necessarily know JS, and I've even seen seasoned developers disregard the recommendations to put the scripts at specific places in the document and then proceed to wonder why they're sporadically losing tracking data.

I've gotten some good feedback from structuring documentation in such a way that a section gradually builds up from the basic knowledge into more domain-specific information [1]

The idea is that you can quickly scan `<code>` sections if all you want is to copy-paste blindly or just speed-read code, but you can "zero in" to a section by reading the accompanying paragraph(s). The guide aims to get to the reader's end goal - i.e. "how to use this thing" - by cutting as many details as we can get away with (and then supplementing the nitty-gritty details in the API section).

I also have the API section landing page be a cheat sheet, which serves as a quick references and a gateway to drill down into the relevant API section in case the sought information isn't covered by the respective cheatsheet section. I find that it's helpful to have a slightly longer "laundry list" that has some context than just having a shorter dry list of disjointed API method names in a left nav (though I do provide the dry nav as well for the power users).

Another thing I find problematic in a lot of docs that I try to address is information architecture. Often times, sites just cobble together a bunch of disjointed sections, which doesn't really help someone who doesn't already know the ins-and-outs of your thing. I try to order the menu items by how advanced are the topics they cover (i.e. tutorials first, followed by more nitty-gritty resources, followed by implementation details).

In my opinion, the biggest challenge is to shift mentality from "Oh, I should write about X, and I guess I need to link to it from the menu somewhere" to "what kinds of things would I search for if I was trying to do X/Y/Z, and where would I go to find that information". This exercise can help uncover areas where more linking can help a user understand the relationship between various parts of the system. Another bonus is that it can also help you write more clearly when you have to assume that a user might land in a given section of docs from a link (rather than having the context from the paragraph above).

[1](https://mithril.js.org/#getting-started)

> I could go on for years about all sorts of interesting tips for improving your writing

Please do! Do you have a blog or something to follow?

I write here and there on my personal site [1].

The intended audience of the few things I’ve written were geared more towards practicing technical writers, but maybe it’s high time to cover the fundamentals.

There’s a mailing list at the bottom of the post I’ve linked to, where you can get a ping whenever I publish a new technical writing post.

[1] https://kayce.basqu.es/on/metrics

I really enjoyed your blog! Please keep writing.

Ditto!