3 ms·

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

> 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

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).