This.
What bugs me is that often they do have times to answer questions, but not to document the product.
And then when the next person is hired and asks the same questions, they still don't have time to document but do have time to answer questions. And again with the next newhire.
Yes, part of this is my responsibility to document as a new hire. That said, I didn't build the system and it would take me longer to document then the original author or existing senior.
If they've got the time to answer the questions, then at least that answer should be documented. Even if they don't have time to document everything, you can at least document the parts that people are actively asking / unsure about, and having a fresh pair of eyes document the system can be helpful (can make the documentation easier to understand for newbies, who are the target audience for documentation usually).
Supporters of heavy documentation seem to emphasize its value in communicating functionality to other programmers, whereas opponents seem to emphasize the hassle of writing it and keeping it up-to-date.
I think a key to documentation that is both easy to understand and easy to maintain is to have good usage examples of the code. They are a very straightforward and concise way of conveying both 1) what something does and 2) how to use it. I like to say, "the right usage example can be worth 1000 words of documentation."
Check out https://sourcegraph.com (disclaimer: I am one of the creators). It parses/analyzes the code to identify function calls, type references, etc., and uses that to show you how a piece of code is used. Currently supports Python, node.js, Go, and Ruby. Would love to hear anyone's feedback!
See the image here: http://i.imgur.com/SAwSGaL.png. What do I get from seeing these properties? It doesnt seem like autogenerated documentation from source code is easy or possible at all. The modules being listed in the modules tab dont seem to be correct, (assert(value: bool, message: string)?
assert is commonly used as a function, but in this case, it turns out to be a module as well. You can see this by clicking on that module link; you'll go to a page that shows assert.js and see that module.exports is assigned to the ok function (which you can click on to jump to its definition). Other attributes are also defined on module.exports, however, so you can see that you can not only do "assert(condition, message)" but also "assert.equal(condition, message)", "assert.notEqual(condition, message)", "assert.deepEqual(condition, message)", etc.
You're right, auto-generating docs is not easy! Javascript turns out to be one of the toughest languages to do this for, and we have a long way to go. The properties tab doesn't seem very useful on that page. We're pushing a new change to the UI that will hopefully make this page clearer and more useful in the near future. Please send any more feedback our way!
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.
...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.
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 ;)
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!
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.
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.
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.
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]
I know this might sound bad but I'm so glad that clean Smalltalk code is millimetres away of being self documented code.
The thing is that you can approximate that with other technologies too. The problem isn't the code or technologies, the problem is the synthesis power (or lack of it) of the developer.
Developers too often get themselves lost in the details and the abstraction pitfalls barely remembering why the heck they did what they did (AKA applicability and purpose)
One of the things that I consider a must from a programmer:
1.She should learn to draw if she does not already.
2.She should learn to do a podcast if she does not already.
Basic documentation is very easy to do, you just talk in a podcast explaining what you have done, like the forensic doctor in a police TV series with a sound recorder.
So easy, now you add some handrawings and presto!
Now if you need to do something more serious with a specific part of the code, the exposed part, you just listen to yourself and spend some time reworking it in paper.
People do surprise how much they forget over long periods of time.
"So, here we use Unique Software X."
"Great! Is there anything to help me learn how to use it?"
"... No. It was just developed over the years."
"I'll even take a powerpoint presentation, even if its outdated."
"Yea, no. You're just going to have to play with it and hope that that's enough to do your job."
"I was going to play with it anyways, but I'm guessing no one has the time to answer questions either?"