I write the docs for Chrome DevTools and Lighthouse. In the discussion for part 1 of this series I mentioned that the #1 most critical skill for creating useful docs is to know your audience. combatentropy expanded on the idea [1] to include purpose:
> 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.
These articles are fine, they have good tips. But, after 8 years of professional technical writing, I strongly recommend focusing on knowing your audience and their purpose. This is a superskill that you can apply to improve any communication.
100% agree with knowing your audience and purpose. But you are a technical writer, so these tips might be obvious. Audience and Purpose could be Part 3?
But for people that don't do technical writing day to day, it can be a little daunting when you are initially tasked with writing some docs. This is usually the case at smaller companies where people have to wear multiple hats.
I always start with the audience in any writing. I'm often asked, "write documentation for your tool" by technical peers and managers and I always have to push back trying to get more specifics. Am I writing for a non-technical end-user? Am I writing for a technical person troubleshooting the tool (can I assume they know yaml or how to use a Terminal)? Am I writing for someone who may reimplement or heavily modify this tool. Is this intended for reference or to walk someone through the process for the first time? All of those are documentation and technical writing, but vary greatly in what details you include and how you approach it.
In my experience, as a tool writer/maintainer I tend to want to document the implementation, but nobody cares about that until you leave your job (by then the documentation may be out of date if you don't maintain it). Most people's highest priority is a troubleshooting guide (which is difficult with a new tool) and a very explicit walkthrough for non-technical people (which is difficult to maintain because dialogs get tweaked and supporting tools can change).
> But for people that don't do technical writing day to day, it can be a little daunting when you are initially tasked with writing some docs.
This is what I'm trying to help with. If you keep the framework of "know your audience" and "know their purpose" in mind, docs will be much less daunting. Who am I writing this for? What do they know beforehand? What is their purpose of reading this doc? Answer those questions, and you won't need to memorize long lists of specific tips. Trying to memorize tips and grammar rules without having an overarching framework of why they improve your communication is what makes writing daunting, IMO.
I've been reading a stark comparison recently, ReasonML vs MDN. I realise this is unfair as MDN has had much more resources and time and the ReasonML docs are a straight copy of the OCaml docs, but compare the Reason List.map [0] vs MDN Array.map [1].
Given that the Reason docs are taken from OCaml and modified , I was wondering how well it would work to take the MDN docs and modify the relevant subset for Reason.
Does any one else find the site design frustrating? Constant top/bottom bars and a full window height of low-quality content before the article begins.
because the population of native North American ethnicities is on decline and biologists are all racist misogynists claiming that there is such an absurd thing as biological sex //sarcasm is not even enough to describe this lunacy that's eating the world//
> //sarcasm is not even enough to describe this lunacy that's eating the world//
The author’s “accidental racism” phrasing is a little awkward, but the idea is there. The point isn’t that “whitelist” and “blacklist” are “racist terms.” Clearly, they are not. The point is that members of the audience for your documentation, paying members and influencing members, could be harmed by them in certain contexts. We don’t always have control over the context or situation in which the user encounters the documentation. For example, I could say that your response is "hysterical," indicating that I find the notion that this is "eating the world" to be overly emotional and alarmist. If you, or another reader, were female, you might then object that "hysterical" shares its root word with "uterus," and its etymology and current shading indicates "characteristic emotional and mental weakness that stems from having a uterus, i.e., from being or being like a woman."
Writing is an exercise of power. It is even more so than verbal speech, in the context of documentation especially, because it provides no forum for the user, your paying user, to clarify and to point out offenses. And take a deep breath, because even if this lunacy eats the entirety of software documentation, the world will be nowhere near consumed. You might even be richer for it, in both senses of the word.
Yeah, I agree. I should also add that in order to avoid "accidental communism" we should stop using phrases like "shared resources", after all if you at the first linked wikipedia article you will find why it's relevant.
It true that writing is a tricky thing since we can't convey intonation and the use of emojis in docs usually is not somethings that's helping the cause. I don't know how it can be solved but if we'll take the way of the word policing you should be inclusive and surely ban: "shared resources", "killing processes" etc etc - there should be no end to this until we reach Farrenheit 451, how "hystorical" (intenstionally misspelled) this might might seem to you. Cheers
The people who aren't going to be impacted particularly regardless of which phrasing you use may not care, nor even notice. It's the folks that get harmed by this who will notice and probably say nothing about it in specific, but will be more likely to adopt your thing, share your thing, tweet nice things about your thing etc.
Or to paraphrase DHH[1], it costs very little to adjust your terms but can have an outsized impact on a portion of your users/developers who are otherwise marginalized.
I get "harmed" emotionally every day reading the words on the internet, not probably - but there isn't any way for me to be able to point a finger to every direction and show even a small proportion of those people how wrong they are (hell maybe I should quit twitter...). If every sentence would be redacted to suit my feelings as well as all other "harmed" individuals" we could as well ban the whole text communication on the internet.
Could we just communicate in binary and be done with it allready /s
For reasons that are too complex for an HN comment on too little sleep, too early in the morning, I'm less hung up on some idea of justice in the world than I used to be. But just as a point of enlightened self interest, if you use less exclusionary language, you are likely to have more buy in from a broader audience, thereby making your thing more successful.
Hm, good link. Maybe we all should waive the white flag of surrender and declare "white" the primary color of the LGBTQXYZ rainbow (since it composes all the colors). No-one could ever be made happy when everyone takes pleasure in being offended.
I write the docs for Chrome DevTools and Lighthouse. In the discussion for part 1 of this series I mentioned that the #1 most critical skill for creating useful docs is to know your audience. combatentropy expanded on the idea [1] to include purpose:
> 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.
These articles are fine, they have good tips. But, after 8 years of professional technical writing, I strongly recommend focusing on knowing your audience and their purpose. This is a superskill that you can apply to improve any communication.
[1] https://news.ycombinator.com/item?id=17839052
100% agree with knowing your audience and purpose. But you are a technical writer, so these tips might be obvious. Audience and Purpose could be Part 3?
But for people that don't do technical writing day to day, it can be a little daunting when you are initially tasked with writing some docs. This is usually the case at smaller companies where people have to wear multiple hats.
I always start with the audience in any writing. I'm often asked, "write documentation for your tool" by technical peers and managers and I always have to push back trying to get more specifics. Am I writing for a non-technical end-user? Am I writing for a technical person troubleshooting the tool (can I assume they know yaml or how to use a Terminal)? Am I writing for someone who may reimplement or heavily modify this tool. Is this intended for reference or to walk someone through the process for the first time? All of those are documentation and technical writing, but vary greatly in what details you include and how you approach it.
In my experience, as a tool writer/maintainer I tend to want to document the implementation, but nobody cares about that until you leave your job (by then the documentation may be out of date if you don't maintain it). Most people's highest priority is a troubleshooting guide (which is difficult with a new tool) and a very explicit walkthrough for non-technical people (which is difficult to maintain because dialogs get tweaked and supporting tools can change).
> But for people that don't do technical writing day to day, it can be a little daunting when you are initially tasked with writing some docs.
This is what I'm trying to help with. If you keep the framework of "know your audience" and "know their purpose" in mind, docs will be much less daunting. Who am I writing this for? What do they know beforehand? What is their purpose of reading this doc? Answer those questions, and you won't need to memorize long lists of specific tips. Trying to memorize tips and grammar rules without having an overarching framework of why they improve your communication is what makes writing daunting, IMO.
Any practical advice for doing this better? Or concrete examples of times you have done this in the past?
By “practical advice on this” do you mean how to learn more about your audience and their purpose?
I've been reading a stark comparison recently, ReasonML vs MDN. I realise this is unfair as MDN has had much more resources and time and the ReasonML docs are a straight copy of the OCaml docs, but compare the Reason List.map [0] vs MDN Array.map [1].
Given that the Reason docs are taken from OCaml and modified , I was wondering how well it would work to take the MDN docs and modify the relevant subset for Reason.
[0]: https://reasonml.github.io/api/List.html#VALmap
[1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...
Does any one else find the site design frustrating? Constant top/bottom bars and a full window height of low-quality content before the article begins.
I always wonder what people are talking about, but I've had this extension for so long that I forgot how bad medium is.
"Make medium readable again"
https://chrome.google.com/webstore/detail/make-medium-readab...
There were some discussions about that here before. One of them is this "Make Medium readable again": https://news.ycombinator.com/item?id=16516126
edit: Removed Markdown
Nice set of guidelines. Mostly "common sense" but given how (un)common that can be, this is likely pretty helpful for its intended audience. :)
> Protip: Avoid accidental racism by using “denylist” and “allowlist,” instead of “blacklist” and “whitelist.”
I actually misread it as denyalist, who knows denialism maybe is the right word after-all.
Not being from US, I had no idea that these were racist terms:
https://en.wikipedia.org/wiki/Blacklisting https://en.wikipedia.org/wiki/Whitelisting
Maybe we should also stop using: https://en.wikipedia.org/wiki/Red_List_Index
because the population of native North American ethnicities is on decline and biologists are all racist misogynists claiming that there is such an absurd thing as biological sex //sarcasm is not even enough to describe this lunacy that's eating the world//
> //sarcasm is not even enough to describe this lunacy that's eating the world//
The author’s “accidental racism” phrasing is a little awkward, but the idea is there. The point isn’t that “whitelist” and “blacklist” are “racist terms.” Clearly, they are not. The point is that members of the audience for your documentation, paying members and influencing members, could be harmed by them in certain contexts. We don’t always have control over the context or situation in which the user encounters the documentation. For example, I could say that your response is "hysterical," indicating that I find the notion that this is "eating the world" to be overly emotional and alarmist. If you, or another reader, were female, you might then object that "hysterical" shares its root word with "uterus," and its etymology and current shading indicates "characteristic emotional and mental weakness that stems from having a uterus, i.e., from being or being like a woman."
Writing is an exercise of power. It is even more so than verbal speech, in the context of documentation especially, because it provides no forum for the user, your paying user, to clarify and to point out offenses. And take a deep breath, because even if this lunacy eats the entirety of software documentation, the world will be nowhere near consumed. You might even be richer for it, in both senses of the word.
Yeah, I agree. I should also add that in order to avoid "accidental communism" we should stop using phrases like "shared resources", after all if you at the first linked wikipedia article you will find why it's relevant.
It true that writing is a tricky thing since we can't convey intonation and the use of emojis in docs usually is not somethings that's helping the cause. I don't know how it can be solved but if we'll take the way of the word policing you should be inclusive and surely ban: "shared resources", "killing processes" etc etc - there should be no end to this until we reach Farrenheit 451, how "hystorical" (intenstionally misspelled) this might might seem to you. Cheers
The people who aren't going to be impacted particularly regardless of which phrasing you use may not care, nor even notice. It's the folks that get harmed by this who will notice and probably say nothing about it in specific, but will be more likely to adopt your thing, share your thing, tweet nice things about your thing etc.
Or to paraphrase DHH[1], it costs very little to adjust your terms but can have an outsized impact on a portion of your users/developers who are otherwise marginalized.
[1] https://twitter.com/dhh/status/1038083068760752129
It does marginalize the whole BDSM community though. If it's an "an easy win" it surely isn't for everyone, it's never is.
> and probably say nothing about it in specific
I get "harmed" emotionally every day reading the words on the internet, not probably - but there isn't any way for me to be able to point a finger to every direction and show even a small proportion of those people how wrong they are (hell maybe I should quit twitter...). If every sentence would be redacted to suit my feelings as well as all other "harmed" individuals" we could as well ban the whole text communication on the internet. Could we just communicate in binary and be done with it allready /s
For reasons that are too complex for an HN comment on too little sleep, too early in the morning, I'm less hung up on some idea of justice in the world than I used to be. But just as a point of enlightened self interest, if you use less exclusionary language, you are likely to have more buy in from a broader audience, thereby making your thing more successful.
Check this classic from Doug Hofstadter out: https://www.cs.virginia.edu/~evans/cs655/readings/purity.htm...
It's hard to hear these things from the other side; that person paper can help with that, I think. It opened my eyes a little.
Hm, good link. Maybe we all should waive the white flag of surrender and declare "white" the primary color of the LGBTQXYZ rainbow (since it composes all the colors). No-one could ever be made happy when everyone takes pleasure in being offended.