4 ms·

I'm a technical writer. I write the docs for Chrome DevTools and Lighthouse. The tips in this article are mostly fine. Nothing controversial there. It has some

I'm a technical writer. I write the docs for Chrome DevTools and Lighthouse. The tips in this article are mostly fine. Nothing controversial there. It has some good advice, but ironically, the article itself doesn't follow its own advice. > The first two paragraphs must state the most important information. The most crucial skill for creating quality documentation is to know your audience and then write for that particular audience. What knowledge are they bringing into the doc (and therefore you don't need to cover)? What knowledge are you assuming that they know? What if they don't have that knowledge? Hint: They'll probably find your doc confusing and frustrating. What is their likely emotional state going into a doc? E.g. if you're documenting an error code there's a higher chance that they're panicked, so don't waste their time! Given a particular audience, what exactly is "the most critical information"? "Know thy audience" is one of those concepts where, the more you think about it, the less you realize you know. It's a lifelong journey. But the more you focus on this concept, the better all of your communication will get. I could go on for years about all sorts of interesting tips for improving your writing, but it's all a waste of time if you don't have an overarching guiding principle. And that principle is to know and write for your audience.

misterbowfinger 8y ago
> 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?
- kaycebasques 8y ago
  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 https://kayce.basqu.es/on/metrics
  - maxhallinan 8y ago
    I really enjoyed your blog! Please keep writing.
    - chrisweekly 8y ago
      Ditto!
ghaff 8y ago
>"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."
- kaycebasques 8y ago
  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.
  - ghaff 8y ago
    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.
    - kaycebasques 8y ago
      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.
- rhizome 8y ago
  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.
forapurpose 8y ago
> "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.
- ASinclair 8y ago
  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.
- kaycebasques 8y ago
  > 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.
lhorie 8y ago
> 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 https://mithril.js.org/#getting-started)
combatentropy 8y ago
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.

misterbowfinger 8y ago

> 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?

kaycebasques 8y ago
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 https://kayce.basqu.es/on/metrics
- maxhallinan 8y ago
  I really enjoyed your blog! Please keep writing.
  - chrisweekly 8y ago
    Ditto!

ghaff 8y ago

>"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."

kaycebasques 8y ago
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.
- ghaff 8y ago
  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.
  - kaycebasques 8y ago
    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.
rhizome 8y ago
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.

forapurpose 8y ago

> "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.

ASinclair 8y ago
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.
kaycebasques 8y ago
> 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.

lhorie 8y ago

> 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 https://mithril.js.org/#getting-started)

combatentropy 8y ago

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.