> 2. Rails' documentation is generated from source, so is Node's. A lot of documentation is. I don't think that's the problem he is talking about. Whether you

> 2. Rails' documentation is generated from source, so is Node's. A lot of documentation is. I don't think that's the problem he is talking about. Whether you put your prose in a separate file or as a special comment in a source file is not a relevant difference. Having prose, and having a sensible TOC, is. Broadly speaking, generated docs tend to be worthless for smaller, well-designed packages, i.e. those where you can browse and read the code+comments in your IDE comfortably. But large and poorly designed packages definitely need generated docs, because their code isn't easily traversed. Basically I think generated references are a necessary evil. If your project needs them I think that's a wrinkle on the project.