You are what you document
brikis98.blogspot.com
brikis98.blogspot.com
"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?"
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).
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!
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!
This situation is very common at startups, for example.
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.
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 ;)
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.
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'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]
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.
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)
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.