4 ms·

I'm probably in a rather small minority here, but I believe documenting things you know are very likely to change can be irresponsible (or at least unwise) if y

I'm probably in a rather small minority here, but I believe documenting things you know are very likely to change can be irresponsible (or at least unwise) if you know the resources needed to update the docs are unlikely to be available. This situation is very common at startups, for example.

timr 12y ago
...and having worked with Bill at a startup with a lot of undocumented code, I can say that he's absolutely incorrect. ;-) If you anticipate that anyone will ever use or maintain your code in the future (including you), you should document it. The communication overhead of an organization grows as the square of its size, so the returns on the fixed amount of work involved are exponential.
- joekrill 12y ago
  THANK YOU. It really just baffles me how hard it is to get some people to document a little, and how some people are ACTIVELY against it.
- abstractbill 12y ago
  If you anticipate that anyone will ever use or maintain your code in the future (including you), you should document it. Right, I think we don't disagree that much. In particular, if you don't anticipate your code being used or maintained for very long, don't document it! Both of us worked on a lot of throw-away code over the years after all ;)
  - sanderjd 12y ago
    This reminds me of this frequent YAGNI-vs-"design" debate that keeps coming up as well. It all comes down to how educated your guesses are about the future of whatever you're building!
    - timr 12y ago
      Yeah, but in this case the losses are bounded, and the upside is huge. You spend 10% (or whatever) of your coding time maintaining documentation, and your long-term expected value is much higher than that. Even if you're not able to predict what code gets re-used and what code doesn't, it's one of the highest-payoff bets you can make in software. About the only times I accept Bill's premise is when you know that you're doing something throwaway (i.e. never gets checked in), or when you're so pressed for time that the cost of doing the documentation is the difference between success and failure (but if you're that bad off, you're doomed anyway). Most of the time, documentation doesn't get written because it isn't immediately "fun" for the coder, and nobody is enforcing it. There's no rational reason otherwise.
      - sanderjd 12y ago
        Well, I might agree with you, or I might not, depending on how we're defining "documentation". If we're talking about the sort of documentation the OP is talking about, which is crucial for any interface that you're releasing to the public, then I don't agree. Documentation like that impedes change and its value doesn't always come out on the right side of the trade-off. Now, if we're talking about more informal documentation used to clarify thought process in confusing areas or writing good commit messages to document the thought process behind a set of changes, then yeah, I agree that everybody should always do that.
penguindev 12y ago
Yes and no. Having design N written up decently might make designing N+1 easier / faster. I also agree with the article that readme-driven-development can make dev (of N) smoother. I've found the hardest thing is really deciding what to build. And figuring that out can be helped by writing a lot of docs early. [edit: or prototyping, of course, but they aren't mutually exclusive and depending on how you divide roles that might not be an option]
Htsthbjig 12y ago
I consider irresponsible and unwise NOT to document something that is going to change. In particular, when I change something I need to know the interface with detail, the input and the output and EXACTLY what the black box is expected to do, special cases included. I just cant tell you how much time I have wasted in my life because the original programmer FORGOT the interface, or its details.(Hey, I made this 6 month ago, Do you expect me to remember the details?) I couldn't care less about the blackbox if we are going to change it, but its behavior needs to be documented.

timr 12y ago

...and having worked with Bill at a startup with a lot of undocumented code, I can say that he's absolutely incorrect. ;-) If you anticipate that anyone will ever use or maintain your code in the future (including you), you should document it. The communication overhead of an organization grows as the square of its size, so the returns on the fixed amount of work involved are exponential.

joekrill 12y ago
THANK YOU. It really just baffles me how hard it is to get some people to document a little, and how some people are ACTIVELY against it.
abstractbill 12y ago
If you anticipate that anyone will ever use or maintain your code in the future (including you), you should document it. Right, I think we don't disagree that much. In particular, if you don't anticipate your code being used or maintained for very long, don't document it! Both of us worked on a lot of throw-away code over the years after all ;)
- sanderjd 12y ago
  This reminds me of this frequent YAGNI-vs-"design" debate that keeps coming up as well. It all comes down to how educated your guesses are about the future of whatever you're building!
  - timr 12y ago
    Yeah, but in this case the losses are bounded, and the upside is huge. You spend 10% (or whatever) of your coding time maintaining documentation, and your long-term expected value is much higher than that. Even if you're not able to predict what code gets re-used and what code doesn't, it's one of the highest-payoff bets you can make in software. About the only times I accept Bill's premise is when you know that you're doing something throwaway (i.e. never gets checked in), or when you're so pressed for time that the cost of doing the documentation is the difference between success and failure (but if you're that bad off, you're doomed anyway). Most of the time, documentation doesn't get written because it isn't immediately "fun" for the coder, and nobody is enforcing it. There's no rational reason otherwise.
    - sanderjd 12y ago
      Well, I might agree with you, or I might not, depending on how we're defining "documentation". If we're talking about the sort of documentation the OP is talking about, which is crucial for any interface that you're releasing to the public, then I don't agree. Documentation like that impedes change and its value doesn't always come out on the right side of the trade-off. Now, if we're talking about more informal documentation used to clarify thought process in confusing areas or writing good commit messages to document the thought process behind a set of changes, then yeah, I agree that everybody should always do that.

penguindev 12y ago

Yes and no. Having design N written up decently might make designing N+1 easier / faster. I also agree with the article that readme-driven-development can make dev (of N) smoother. I've found the hardest thing is really deciding what to build. And figuring that out can be helped by writing a lot of docs early. [edit: or prototyping, of course, but they aren't mutually exclusive and depending on how you divide roles that might not be an option]

Htsthbjig 12y ago

I consider irresponsible and unwise NOT to document something that is going to change. In particular, when I change something I need to know the interface with detail, the input and the output and EXACTLY what the black box is expected to do, special cases included. I just cant tell you how much time I have wasted in my life because the original programmer FORGOT the interface, or its details.(Hey, I made this 6 month ago, Do you expect me to remember the details?) I couldn't care less about the blackbox if we are going to change it, but its behavior needs to be documented.