It's obvious that something needs to be done about the S2 manual. At the moment it's a bit of a confused mess, not really sure whether it's LiveJournal user documentation, S2 technical documentation or a technology whitepaper. I think the only way we can deal with this is to split it off into two separate manuals. The user-centric one, called the “S2 User Manual” will start from the basics and eventually work its way up to describing the entire system and language. The “S2 Developer Manual” will describe the system with the assumption of technical knowledge and will probably include much of the current S2 manual as well as some documentation on the S2 runtime, how to embed S2 into web applications and so forth.
I made a start on a possible S2 User Manual as an example of what I mean. As usual, I must disclaim that writing documentation for users isn't what I normally do, although I think I'm getting better at it as I continue to write these kinds of things. With that said, then, I'd like it if people would have a read of the introduction and first chapter so far and comment on it. In particular, are there places where I'm too patronising or where I move to fast and skip over necessary detail? Developers probably aren't the best people to ask about this, but I thought I'd ask here first because until I've got a bit more guts most users probably won't “get it” yet. (it doesn't really tell you much at the moment)