

You are what you document - nkurz
http://brikis98.blogspot.com/2014/05/you-are-what-you-document.html

======
drdeadringer
My valuing documentation grew from being the user at various jobs, something
like this:

"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?"

~~~
click170
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.

~~~
SyneRyder
I always thought Derek Sivers covered this well with his Delegate Or Die
essay:

[http://sivers.org/delegate](http://sivers.org/delegate)

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

~~~
drdeadringer
I remember reading this post, and liked the idea.

------
beliu
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](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!

~~~
Meai
See the image here:
[http://i.imgur.com/SAwSGaL.png](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)?

~~~
beliu
Thanks for the 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!

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

~~~
abstractbill
_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
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
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
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.

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

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

