My ears are red from @kyledrake's @ mention, so I thought I'd stop by and express some opinions. :)
Code != Docs
I don't have full context here, but working off Kyle's assertion that pervasive unit testing is effective developer documentation, I have to disagree. Code, whether it's example code, unit tests, or the library code itself, is not documentation. It's like an image or a figure, which can be very informative as long as there's sufficient context to explain it. There still needs to be a natural-language explanation that accompanies even the most clear and straightforward code. The common assertion that "our consumers are developers, so of course they can read the code as well as English" is naive, because code and natural language operate differently in terms of semantic model, purpose, range of expression, and the consumer's frame of reference for understanding and cognition.
To dig a little deeper, one of the reasons why the current situation is problematic is that the unit tests files are full of noise. There's structure for the BDD framework, for mocking, for asserting results, for populating fixtures, etc. This noise confuses a new dev. Which parts are tests, which parts are lib code? Is this the ideal way to use it or just one of the possible ways to use it? When should I use this particular option instead of that one? Etc.
A good example should be standalone and executable without anything else in it other than what's needed to accomplish the example, and with lots of commentary about what the various bits do and why they are needed.
Combatting Bit-Rot
That said, bit rot is evil and the worst thing in the world for docs. I've spent the past 6 months working on documentation-focused CI systems at Twitter, with the primary goal of building tooling to prevent documentation bit-rot (I like to call it "drift" or "health"). This is exactly why.
I think docs should be testable and verifiable. I think unit tests and example code should work together with docs to create a complete learning environment that is always up-to-date and accurate.
I agree with Kyle in that, if you don't have the resources to maintain docs in addition to unit tests that the unit tests might be more valuable, specifically because they are currently verifiable in an automated fashion. All example code should also be verified in an automated fashion and just be treated as high-level integration testing, as well as teaching material. Human-language descriptions should accompany all unit tests and examples.
Lazy vs Complete? Better tools are the answer.
It's not a matter of being lazy or not, it's a matter of being complete in your output. Back in 2001, shipping code without unit tests was acceptable, normal practice. Only zealots and crazy people spent the time to fully test their code and keep it up to date. Many people viewed unit testing as a waste of time, extra work, and pointless. Now, in 2014, we have a changed perception of unit tests. Code that does not have unit tests is considered incomplete, and therefore not fully shippable. I feel like documentation needs to be included in that mantra. Right now we're having the same nature of discussions about docs in 2014, as we were about unit tests in 2001. In the end, tooling is the answer. That's what made unit testing pervasive, not shaming, or pressure. Good tools that made it easy to do the right thing.
I'd challenge this project to consider what tools might make this easier, then maybe we could hand-roll tools to fill in the gaps for this project. Failing that, what currently available tools get us to a reasonable compromise?
Perhaps the unit tests could be converted to use literate programming? (eg https://www.npmjs.org/package/literate-programming or http://jashkenas.github.io/docco/)
At minimum, toss in some embedded multi-line commentary in the unit test files. When you update code, make sure to update the comments. We could even write a simple git log parser that would detect this situation and alert. Imagine something that looked at a changeset, determined that code changed in a given unit test, but that the comment string associated with that test didn't change, and would warn on the command-line with a simple check like grunt doctest.
Docs Are A Garden, Not A Sculpture
Regarding @TimDaub's offer to improve docs, first and foremost, any "we lack resources" arguments are obviated by Tim's offer. However Tim's offer brings up another important point: Docs are a garden, not a sculpture. They are a living thing, and need ongoing maintenance. It's not a one-time work of art that lasts 1000 years like a marble statue. So, Tim (or anyone wanting to contribute docs) should understand that docs are not a one-time PR but rather an on-going responsibility.
When someone drives-by and commits docs once, then leaves them to bit-rot as the code moves forward.. well that, isn't helping very much. In fact, it's the kind of help that ultimately hurts later on. The project maintainers might be better off rejecting that kind of offer and sticking with what they can manage with the current team. So, I'd ask you @TimDaub : Are you willing to not only write the docs, but also maintain them indefinitely in the future (or, if you have to bow out, find someone to pick up that responsibility)?
So in summation, I don't think the current approach is sufficient, but I'd like to encourage you all to be creative with ideas about how to incrementally improve the documentation without allowing bit-rot to creep in. Most importantly, I'd like to see documentation be given the same level of concern and import as the code itself.
Thanks,
Troy
PS: @kyledrake .. this would be a great WTD 2015 talk!