5 ms·

> 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 tr

> 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 ago
In 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.
  - Jensson 4y ago
    As I said, well written documentation is impossible unless the codebase is very clean, and trivial to write if the codebase is clean. For anything else the documentation will either be very sloppy with details, span hundreds of pages making it unwieldy compared to browning code where you have tooling to see references etc. I have written and reviewed many design documents and held presentations, I understand the value of communication, but that value just isn't there for most codebases since their abstractions are way too leaky for documentation to provide any value. A design document explaining why the service or library was built and the design decisions originally taken is often useful since it provides context, but things lower level than that just isn't useful in most codebases people work in. > 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. You need to practice reading code and have empathy for the original programmers so you understand their thinking. The original design documents helps a lot with that, then the general naming schemes and such start to make sense and its smooth sailing just reading the code after that. If the codebase was written without any deliberate design or architecture then you have bigger problems than missing documentation...
    - BlueTemplar 4y ago
      Well, yes, like for code comments, the most important parts are the whys. You're also forgetting that in some situations the source code itself might be unreadable to the person : either because it's just not available (including the comments), or because the reader doesn't know the programming languages (with assembly programming being a bit of both).

Jensson 4y ago

In 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.
- Jensson 4y ago
  As I said, well written documentation is impossible unless the codebase is very clean, and trivial to write if the codebase is clean. For anything else the documentation will either be very sloppy with details, span hundreds of pages making it unwieldy compared to browning code where you have tooling to see references etc. I have written and reviewed many design documents and held presentations, I understand the value of communication, but that value just isn't there for most codebases since their abstractions are way too leaky for documentation to provide any value. A design document explaining why the service or library was built and the design decisions originally taken is often useful since it provides context, but things lower level than that just isn't useful in most codebases people work in. > 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. You need to practice reading code and have empathy for the original programmers so you understand their thinking. The original design documents helps a lot with that, then the general naming schemes and such start to make sense and its smooth sailing just reading the code after that. If the codebase was written without any deliberate design or architecture then you have bigger problems than missing documentation...
  - BlueTemplar 4y ago
    Well, yes, like for code comments, the most important parts are the whys. You're also forgetting that in some situations the source code itself might be unreadable to the person : either because it's just not available (including the comments), or because the reader doesn't know the programming languages (with assembly programming being a bit of both).