15 ms·
> The cartoonist Richard Guindon has a famous quote: “writing is nature’s way of letting you know how sloppy your thinking is.” You might have an impression tha
by Jensson 4y ago
> The cartoonist Richard Guindon has a famous quote: “writing is nature’s way of letting you know how sloppy your thinking is.” You might have an impression that you understand something well, but that sense of clarity is often an illusion, and when you go to explicitly capture your understanding in a document, you discover that you didn’t understand things as well as you thought. There’s nowhere to hide in your own document.
Coding is natures way of showing how sloppy your thinking is, not writing natural language text. It is really easy to hide sloppy thinking behind natural language, otherwise there would be a lot of overlap between great writers and great coders, but there doesn't seem to be much correlation there at all. Coders tend to be precise with their language, but most people prefer to read imprecise sentences so you easily gravitate towards imprecise language if you try to practice writing.
- mrich 4y agoAnd testing is nature's way of telling you how sloppy your code is, I suppose? (recursion intended)
- Jensson 4y agoYeah, testing shows you that your code is sloppy, writing is even worse since there is no testing at all, even the worst code is better tested than the best text as long as the programmer ran it once.
- KronisLV 4y ago> writing is even worse since there is no testing at all Isn't it possible to get a beta reader? Just someone who will go through your writing and give you feedback? If you are writing docs, a lot of the time you'll also have coworkers there with you, that you'll be able to float the docs to for a quick look, or maybe other people who are interested in your project, if doing open source, or even a friend. It is a bit worse than automated testing, but surely better than nothing! Also, there are apps or sites like this, that help you detect when you have run on sentences or complicated wording: https://hemingwayapp.com/ https://hemingwayapp.com/ Those could sometimes be useful.
- gandalfgreybeer 4y ago> Coders tend to be precise with their language, but most people prefer to read imprecise sentences so you easily gravitate towards imprecise language if you try to practice writing. Preferring to read imprecise sentences comes down to what the purpose of the written work is, does it not? Clear and precise technical documentation and even research papers are really helpful and can be practiced. If it’s poetry or a level of emotional buildup such as in fiction is needed, then that’s what people will prefer. Context on what is being written matters.
- Jensson 4y agoIn theory yes, in practice documentation tends to be too sloppy to be useful. The problem is that writing all the details is equivalent to just providing the source code, so you need to explain less. But then unless what you are working with has very clean abstractions the documentation becomes worthless because it doesn't explain things well enough. So in practice documentation for a codebase is mostly worthless unless the codebase is very cleanly written, which wont be the case unless we are talking about programming languages or similar. The real documentation people use in codebases is looking at how things are used in other parts of the codebase. Then you have examples and maybe even tests showing how it works, so you start from there and maybe test some things if you need to do things a bit differently. So when is documentation actually useful? When you provide a library that is intended to be used outside of your codebase, so a person who adds the library to his codebase can understand how to use it without having examples to look at in their code. But this is a very specific case and most software engineers don't have to think about it. If I'm missing something here please explain why, but I've never found any documentation to be useful, except for libraries from outside your codebase. And even for libraries it is often easier and faster to just read the source code if it is available. Edit: If you are talking about design documents for services and features then those are useful, yes, but that is usually not what people talk about when they talk about software engineers writing documentation.
- knighthack 4y ago> If I'm missing something here please explain why, but I've never found any documentation to be useful, except for libraries from outside your codebase. And even for libraries it is often easier and faster to just read the source code if it is available. For simple packages, I understand. For anything else, you are committing hyperbolic falsehood if you (or others) claim that it is "easier and faster to just read the source code" and "even for libraries", compared to reading examples/well-written documentation.
- cratermoon 4y ago“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” – Martin Fowler
- olau 4y agoI've personally found that to write a good API, you need both code that implements the API and code that uses it, and you also need to write the documentation of that API. The former reveals flaws in the machine interface, and the latter reveals flaws in the human interface, so to speak. For instance, you might find yourself spending a lot of text trying to explain the naming and then realize that the naming is simply bad.