Good writing is clearly useful and quite often mentioned. But good reading is very rarely talked about. I think it is even more important.
Too many people cannot maintain attention for more than a few seconds while reading. Or they read "what they want to read" instead of the actual text. Like I write a "list of things" and they read it like "a set of things", loosing the meaningful ordering of a list.
I tend to write concise documentation, but people always loose some important details that way. So I am now purposefully adding more text than strictly required to be sure important points are really understood.
Like a good teacher repeats at least 3 times the same matter, with a slightly different angle
This reminds me of an old Spolsky blog post on writing specs: [0]
> Programmers often try to write specs which look like dense academic
> papers. They think that a "correct" spec needs to be "technically"
> correct and then they are off the hook.
>
> The mistake is that when you write a spec, in addition to being
> correct, it has to be understandable, which, in programming terms,
> means that it needs to be written so that the human brain can
> "compile" it.
> Like I write a "list of things" and they read it like "a set of things", loosing the meaningful ordering of a list.
That's on you. A lot of code use list instead of set purely because set is rarely a basic primitive language offers.
If I see method returning list of users I'm just gonna assume it is unordered, and it usually is unordered.
If you return list that's ordered and that matters for some reason, the docs should say it is ordered and by which key.
If the method is called RunTasks(list) and documentation is "runs a list of tasks" it is perfectly fine to assume it means "runs list of tasks in order" but it is also perfectly fine to assume "runs all of the tasks in parallel".
I think everyone is capable of reading well-written text or code. The problem comes when it’s not well written, in which case you’re in the real of reverse engineering. And most people are bad at RE.
