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