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