Good and bad technical writing
I've written a shitload of content in my life. When moving out of my parents', I went through my childhood diaries (cause yes, I didn't use to have friends, but I did use to write diaries) and found an entry from my first year of high school: "Today I had an incident with the wall. I hit the wall. I got injured." 6 years old, and what a poet. So when people ask me how I got into writing, I have the most boring story: I have been doing it since when I was a kid. But when you get a job as technical writer this is not really enough, so I have had to expand it into: I've liked to write since forever, I wrote tech articles as a teenager, my high school teachers advised me to become a journalist, I wrote stories and non-fiction a bit everywhere, I studied math and computer science, and recently wrote intuitive math content, IT docs, and science scripts. But I have also been a teacher on and off for several years, and I have always been very keen on creating pedagogical explanations. That is why I so often cringe when I read through some technical document that is all over the place. I have so many opinions on technical writing, and I am going to expose some of them by picking random pages I have recently had to read and pick out the good and the bad.
Three pairs of quotes, but okay. A
unique object? Adjectives are not ornamental christmas balls, so how does this unique object would compare to a ... non-unique object? What is a producing code and a consuming code? If you think I know already what they are, then you should also know that I would not be reading this page in that case. 80% of the readers will not know what those are, so you cannot give those concepts for granted. And no, the solution is not to open the page with definitions. There is nothing worse than going through a glossary in a technical page.
The "producing code" takes the time it needs to produce the promised result, and the promise makes the result available to the overall subscribed code whenever it's ready.
I still don't know what a "producing code" is. And then the biggest flaw of all: using the word you are defineing to explain that same word. I still don't know what a promise is, and here are we talking about promised result. And what is "the overall subscribed code"? I have no idea. When does it get ready? How do I make it so?
Comma after a leading conjunction, two bold moves. And the whole sentence is just a bullshit filler, saying "promises are complicated! You need an explanation". Gotcha. Thank you. That's why I'm here, but three paragraphs in and I'm still clueless. And also, your time is up: I'm leaving. But let's look at one more sentence that reassures me that I am not losing anything by leaving:
The arguments of it [the function], such as the
And here we get the final confirmation that the writer doesn't know what the words they are writing are about. "Are considered"? A callback is a callback. It's like saying "the time on your train ticket is considered to be the departure time". No, it is. Is this written by somebody that really understands promises? Hard to tell.
A quick sum-up of the flaws:
- lots of concepts given for granted
- using the word
promiseto describe what a
- using language at random: sentences that don't really say anything valuable, adjectives used to make sentences less dry, punctuation not accurately set.
This one starts much better. It starts with an analogy:
Imagine that you're a top singer, and fans ask day and night for your upcoming song. To get some relief, you promise to send it to them when it's published. You give your fans a list.
This is great, I know how singers work, roughly. It doesn't need a lengthy explanation. And, cherry on top, it uses
- A "producing code” that does something and takes time. For instance, some code that loads the data over a network. That’s a "singer”.
- A "consuming code” that wants the result of the "producing code” once it’s ready. Many functions may need that result. These are the "fans”.
I'm still not totally onboard, but it makes a lot of sense so far, so I feel like I'm ready to see a code example and be able to parse it out somehow. I need to read through a filler first though:
Of course it's not accurate: it's an analogy. And that's fine. No physics professor think that water flows are an accurate analogy for electrical currents, but it would be idiotic to not use it. If it aids understanding, it should be used. Of course you cannot use it forever: at some point you have to ditch the analogy and face the harsh truth of electromagnetic fields. They are a new concept, but you can think of them as a 3D something that you know, and it's easier and less intimidating. Ditching analogies for fear of coming out as "not-expert" is wrong. (It does need to aid understanding though. If you have to explain the analogy in detail, it's probably not a good one.)
Anyway. The page then continues with text of mediocre quality, but it is filled with enough technical details spelled out well enough to actually be clear. When the writers forgets that he has to fill a page, he can write coincise sentences that get good content across:
So to summarize: the executor runs automatically and attempts to perform a job. When it is finished with the attempt, it calls
resolveif it was successful or
rejectif there was an error.
This is quite different. One thing is clear: you may disagree with how content is laid out, but you can see that there's been thought from somebody that deeply understood what he was talking about. Notice how every word is carefully laid down in the very first sentence:
Promiseis an object representing the eventual completion or failure of an asynchronous operation.
Notice how it's all words you most likely know already (or you should). Then comes a disclaimer that is quite opaque to a newcomer, but makes a lot of sense.
Since most people are consumers of already-created promises, this guide will explain consumption of returned promises before explaining how to create them.
They flip the exposition. Both previous pages started showing how to create a promise, but what do I care. 80% of people are looking up promises because they were using whatever library, got a weird object returned, checked the type, and found out it was a promise. It makes a lot of sense to flip the exposition so that you are first exposed to how to deal with a promise! It makes it more pedagogical, and relevant to the reader.
Essentially, a promise is a returned object to which you attach callbacks, instead of passing callbacks into a function.
Three sentences in, and I still have no questions. Everything is clear. And now comes the first example. It shows how you would do something without promises, and how you would translate the same thing into using promises. It is saying: "here is what you know already. Now here is how you expand it with this other concept." And then it tells why you should care:
In the old days, doing several asynchronous operations in a row would lead to the classic callback pyramid of doom. With promises, we accomplish this by creating a promise chain. [example]
And then it digs deeper. What's the syntax like in the general case. How do you chain them. What are the common mistakes. Error handling. And more. But it's tidy. They don't assume you know something until they have covered it, and they don't show off their knowledge of terms. They pick an entry point (and picking one is a skill) and work from there in a pedagogical way.
I landed here by pure chance, cause a collegue started working there, but let's read through. This is the very first page of their documentation. It starts with:
An exemplar is a specific trace representative of measurement taken in a given time interval.
I have absolutely no idea of what this sentence means. I can see that the words are carefully laid down, but it's not words I am familiar with. In the Mozilla page, you could assume that 80% of the audience knew every single word of the opening sentence, but here? What is a
trace? What makes it
specific? What is a
measurement? And how do I take a measurement into a trace? I am completely lost.
While metrics excel at giving you an aggregated view of your system, traces give you a fine grained view of a single request;
metrics? What are
traces? Mind you, this is the first real docs page, the first under
Fundamentals and after the
Introduction to Grafana (which is just an intro to the different versions).
exemplars are a way to link the two.
exemplars, which I know nothing about, are a way to link
metrics, which I know nothing about, with
traces, which I know nothing about. That's 46 words that have not led me one inch closer to knowing what the product is, and no links or tooltips either.
Now. The next paragraph switches gears completely:
Suppose your company website is experiencing a surge in traffic volumes. While more than eighty percent of the users are able to access the website in under two seconds, some users are experiencing a higher than normal response time resulting in bad user experience.
Oh, here comes a use-case. I understand web traffic, so this should help me in clarifying
exemplars. Except that I read, and I am puzzled. When system load is high, all users experience "a higher than normal response time". It's not like 80% get a timeout and 20% get a blizzard experience. So the only use case presented in the first
Fundamentals page is... inaccurate?
Use exemplars to help isolate problems within your data distribution by pinpointing query traces exhibiting high latency within a time interval.
Here is a packed sentence saying that these
exemplars will help me in this use-case. It still doesn't tell me how. It doesn't show me how. However, it doesn't miss the chance of saying that "Support for exemplars is available for the Prometheus data source only." What is a
Prometheus data source? What do I care about this piece of information?
I can see many people were involved in writing this page, and a frankenstein came out. Somebody said: we need to have a precise definition [of what?] as opening. Somebody else said: we need to have a practical example. Yet somebody else said: we need to puntualize that this feature doesn't always apply. But nobody was bold enough to take one decision, and all ideas were diplomatically accepted. The result is that the page has no direction, and the reader experience is neglected in favor of not pissing anybody off.
Google Analytics 4 migration
I have a chip on my shoulder with Google Analytics, so I have a hard time holding my temper. But let's try. I'm much more annoyed at the API itself rather than the docs, to be honest.
Indeed, the page itself is not too bad. My main complaint is about the number of links. They send you everywhere, confusing you as to what you should be reading to achieve your goal, and nowhere at the same time, because a third of them are 404s. And information is scattered across all these pages, all with a vaguely similar title, and after you jump a couple links and end up with 10 open tabs that kinda look the same, you start wondering: what the hell should I be reading?
The Data API v1 client libraries were designed to get you started fast. By default, client libraries try to automatically find your service account credentials.
Who would design libraries to get you started slow?