3 ms·

Great list. Let me add a few things: * Ad Precision/Conciseness: When crossing disciplines from Math => Software, this annoyed me to no end: I was not able to

Great list. Let me add a few things: * Ad Precision/Conciseness: When crossing disciplines from Math => Software, this annoyed me to no end: I was not able to express myself concisely. I found that vocabulary is a large part of this, I knew what I meant but did not have the words for it. This is stuff like: call site. caller callee. function signature. deployment vs. installation vs. release Also you need good words to describe the objects/systems that you are building, and the domain your are operating in. This is why NAMING things is so critical. You need to have good words for the concepts you are working with. * Ad Directness: Yes. But try to avoid value judgements and insults. Stay objective: "This code is shit!" vs. "I don't think the case X==0 is handled correctly."

abnry 6y ago
For the developers in the comments, having a better vocabulary is like having a better standard library. If you have to describe the details of a basic data structure every time you bring it up, you will lose the audience. The psychological concept of chunking plays an important role here. By encapsulating a complicated concept into a single package you increase comprehension and the ability to reason. There is the same thing in mathematics where coming up with definitions (standard library functions) are crucial. One of the biggest developments in calculus was a rigorous definition of continuity. The definition itself is complicated. However, once you encapsulate the entire concept into the single word "continuity," you can start exploring and proving many more theorems.
KineticLensman 6y ago
> you need good words to describe the objects/systems that you are building Totally agree! And I would add, once you have come up with a word (or label), stick with it. There is nothing worse, in technical writing, than an author who keeps using different terms for the same thing in a single document. It leaves the reader with the task of keeping track of what is being described, and thus makes the doc harder to read. I think there are several reasons for this: * authors showing off their extensive vocabulary * authors trying to add novelty by using new synonyms * authors who haven't checked other parts of the doc to see what was said elsewhere. In technical writing, the author's job is to communicate as consistently as possible to reduce the cognitive burden on the reader.

abnry 6y ago

For the developers in the comments, having a better vocabulary is like having a better standard library. If you have to describe the details of a basic data structure every time you bring it up, you will lose the audience. The psychological concept of chunking plays an important role here. By encapsulating a complicated concept into a single package you increase comprehension and the ability to reason. There is the same thing in mathematics where coming up with definitions (standard library functions) are crucial. One of the biggest developments in calculus was a rigorous definition of continuity. The definition itself is complicated. However, once you encapsulate the entire concept into the single word "continuity," you can start exploring and proving many more theorems.

KineticLensman 6y ago

> you need good words to describe the objects/systems that you are building Totally agree! And I would add, once you have come up with a word (or label), stick with it. There is nothing worse, in technical writing, than an author who keeps using different terms for the same thing in a single document. It leaves the reader with the task of keeping track of what is being described, and thus makes the doc harder to read. I think there are several reasons for this: * authors showing off their extensive vocabulary * authors trying to add novelty by using new synonyms * authors who haven't checked other parts of the doc to see what was said elsewhere. In technical writing, the author's job is to communicate as consistently as possible to reduce the cognitive burden on the reader.