[zeromq-dev] Docs

[john skaller]

On 15/01/2012, at 6:19 PM, Phil Stanhope wrote:

> As a very interested observer of the mailing list (and part-time 0mq user) ... my advice before implementing a new language binding would be to actually read the entire guide and build all the examples in zguide (http://zguide.zeromq.org).

I'm trying to shortcut that process. I do not want to develop example code in C,
I want to develop them in Felix. So I need the bindings first.

> Looking at the data structures and raw C API without having the context of why 0MQ is what it is ... and how/why it evolved from previous message queuing implementations is critical, IMHO.
> 
> Only after working through each and every example ... breaking them (accidentally / intentionally), would I embark on a new language binding. This is an investment that's well worth it. It took me 3-4 days. It's the ease at building a variety of message processing architectures that you'll find so compelling with 0mq.

Sure. Look, I'm convinced already, that's why I'm creating the bindings :)

But you must understand I'm a compiler writer. My main focus is on the
language and compiler design, and at least half the purpose of adding
a new library is to find out what I need to change to make it easier
to create a binding. You will see shortly when I publish it here   .. it turns out
to be a bit longer than I thought because I decided to make it safe and easy
to use, pushing the language a bit harder to achieve that.

The other half of the reason for making the binding is so OTHER people
can use it.

The point is, the pages have to be precise. I don't want to have to understand
a whole heap of stuff to interpret the semantics. I'd rather complain the docs
are inadequate WITHOUT such background, because it is good for ZeroMQ
to do that.

Experienced users cannot critique or write good documentation.

You need a novice for that, someone that doesn't do precisely what you're
telling me I would gain an advantage from: take the context into account.
Yes, that would help me, but it wouldn't help get the specifications into shape.

[BTW: I have of course read the Guide etc, although it was some time ago
when I previously evaluated ZeroMQ, whilst evaluating Mongrel]

--
john skaller
skaller at users.sourceforge.net