Maybe this is my own preference showing (I always try to work out a spec and a formal semantics first), but I think that even an informal and protean specification is better than no specification at all. To paraphrase Conal Elliott, I'd like these libraries to be precise about 'what', not just 'how'.
I somewhat disagree. It is like Test Driven Development, do you write all the tests first, then the code? It is not my case, I know tests are useful, but while coding, especially something new with lots of unknowns there is a conversation between tests, code, and specification.
My favorite style is also a conversation between tests, code, and spec. I can't recall working on any substantial problem where those stages can be clearly separated during development. In fact, mixing them more often tends to improve results.
User-driven development that starts from surveys or actual use cases wins every time. Hindsight is better than foresight.
Yes. Getting something out-of-the-door without documentation (and examples) is almost useless nowadays.
That depends on how out-the-door it is :) Sending something to a couple of friends without much documentation can be useful. Publishing something to the whole world without documentation is less useful, but can work if the code is really clean.
I expect that having a complete spec document for stable releases, gradually written over the course of a year together with implementation work, would be a good compromise. But there's no way to find out except trying it. So far, less spec-driven processes have been tried in the existing library collections, and more spec-driven ones in SRFI.
I am not sure what is the difference between specification and documentation in the scope of scheme-live?
Good question. Could we write one document that serves as both? Or use docstrings for documentation.
That will be the problem of the implementer. I take the case of JSON parsing: without a light spec such as : need to stream parse JSON, you end up with a much different implementation.
The spec would be driven by: 1) what features users need; 2) what kind of API has good cohesion with the rest of the library collection.
As an example of 2), generators and accumulators could be the standard way to solve a particular kind of problem across the collection. That would lead users to expect that all libraries in the collection provide a generator interface for some kinds of tasks. I.e. generator to read random bytes, generator to read JSON, generator to read zip files, ...
One of the main values in a big library collection is to discover abstractions that work well for a wide range of use cases.
