3 ms·

So true, when I say in engineering school we had a subject called project management and we were taught that you have to write the documentation and everything

So true, when I say in engineering school we had a subject called project management and we were taught that you have to write the documentation and everything first and it should be done in such a detail (including variable names and such) that you can give the project documentation to three different programmers and receive the exact same product from all three. I always hated this approach because of the reasons you stated. I love the quote from that German hacker Fefe: "Coding is an explorative process"

quickthrower2 4y ago
> write the documentation and everything first and it should be done in such a detail (including variable names and such) that you can give the project documentation to three different programmers and receive the exact same product from all three. The only documentation that specific would be … the code!
- kleene_op 4y ago
  No... The only documentation that specific would be the code... plus the documentation!
- pclmulqdq 4y ago
  Programmers seem to think that code is somehow its own documentation. It is not, no matter how readable it is. Documentation is there to provide structure to the reader (no, the class hierarchy in your code and your build files do not do that) and to eschew the unimportant details. Code has a lot of unimportant details that provide cognitive load when reading it, but do not give insight. Documentation is about transferring insight. These are very different things.
  - quickthrower2 4y ago
    I don’t think any English language based documentation can achieve this: > give the project documentation to three different programmers and receive the exact same product from all three. Nit unless the language used is very code-like and pedantically logical to the nth degree.
    - pclmulqdq 4y ago
      That's not what documentation is for. That's not even really achievable by sharing code unless you are sharing a lot of metadata too (exact build setups, compute environments, etc.) or the code is very simple. Documentation is there to _abstract away_ all of the specification that you don't need. That is very valuable if you are ever going to work with other people - it reduces their cognitive load - and it is valuable if you are working on something complex since it also reduces your cognitive load.
      - quickthrower2 4y ago
        I agree with you, I just don't think this is possible with any kind of documentation in the classic sense: > give the project documentation to three different programmers and receive the exact same product from all three. Is like giving a play script to 3 performers, and expecting the same performance. Software development is a creative art. People will deny it but it is true.

quickthrower2 4y ago

> write the documentation and everything first and it should be done in such a detail (including variable names and such) that you can give the project documentation to three different programmers and receive the exact same product from all three. The only documentation that specific would be … the code!

kleene_op 4y ago
No... The only documentation that specific would be the code... plus the documentation!
pclmulqdq 4y ago
Programmers seem to think that code is somehow its own documentation. It is not, no matter how readable it is. Documentation is there to provide structure to the reader (no, the class hierarchy in your code and your build files do not do that) and to eschew the unimportant details. Code has a lot of unimportant details that provide cognitive load when reading it, but do not give insight. Documentation is about transferring insight. These are very different things.
- quickthrower2 4y ago
  I don’t think any English language based documentation can achieve this: > give the project documentation to three different programmers and receive the exact same product from all three. Nit unless the language used is very code-like and pedantically logical to the nth degree.
  - pclmulqdq 4y ago
    That's not what documentation is for. That's not even really achievable by sharing code unless you are sharing a lot of metadata too (exact build setups, compute environments, etc.) or the code is very simple. Documentation is there to _abstract away_ all of the specification that you don't need. That is very valuable if you are ever going to work with other people - it reduces their cognitive load - and it is valuable if you are working on something complex since it also reduces your cognitive load.
    - quickthrower2 4y ago
      I agree with you, I just don't think this is possible with any kind of documentation in the classic sense: > give the project documentation to three different programmers and receive the exact same product from all three. Is like giving a play script to 3 performers, and expecting the same performance. Software development is a creative art. People will deny it but it is true.