Comment by kallsyms

Background: My co-founder and I have been programming for 10+ years each, and like many of you I'm sure, have run into old, incomplete, or entirely incorrect documentation more times than we can count. We believe that this happens for a few main reasons:

First, existing tools don't really support you in writing docs. They may autogenerate a few lines of boilerplate, but nothing links the docs to the code itself. This is true both for top of (function|class) docstrings, but is even more true for documentation which is in completely separate files like READMEs, architecture diagrams, a wiki, etc. We believe that by being more intelligent about understanding what is documenting what, we can make the experience better for everyone, both on the writing side, and also on the reading side.

Second, doc writing is time consuming for something that feels like gives little immediate gain, and is also not ingrained in many companies engineering culture. In reality, it helps your teammates _now_ since they can more easily comprehend what you wrote, and in the long term, it of course becomes necessary as people come and go (or even just to remind yourself of what you wrote a few months ago). It's just hard to be driven to do something when the payoff may be a few months down the line, especially when you have a deadline to ship something next week.

We're curious to hear what you all think both about the product and about the issue in general.

Thanks.