Subject: [lisp] Comments on LISP intro and architecture from today's slides.

From: Paul Vinciguerra <[email-masked]>
Date: Wed, 7 Nov 2012 01:26:33 +0000

I reviewed today's slides and the Jabber logs and have a few comments:

Does the introduction document try to do too much?

Would simpler be better in this case?

My thought is that as an introduction, it should address:
* The background problem/proposed solution.
* "what's in it for me" - the use cases that this architectural change brings to the table.
* The life of the packet to introduce all the elements in context demonstrating their use.

Many of the other sections, for example, 7, 11, and 12 all seem to be more applicable and relate more to the architecture than the intro document.

Paul

---

From: [email-masked] (Noel Chiappa)
Date: Tue, 6 Nov 2012 21:09:46 -0500 (EST)

> From: Paul Vinciguerra <[email-masked]>

    > ...

This sounds like a 'LISP user' document, and that's probably a very useful
document to have, but it's not an 'introduction to LISP for engineers who want
to know a fair amount about how it works internally', which is what the
existing 'Introduction' document is.

(Although to be honest, for a 'user' document, I'm not sure I see the value
of the third topic.)

    > relate more to the architecture than the intro document.

The other document is _not_ 'the architecture document' (and I'm about to
rename it, as soon as the ID block comes off, to emphasize that).

An architecture document covers, to start with, _the architecture_ (duhh),
which starts with talking about i) what the major pieces of the system are,
and ii) how those pieces interact.

None of that is in the second document.

The pair of documents _together_ form an 'architecture' document, as it would
normally be thought of.

What really happened was that there used to be only one 'architecture'
document, and it got too long, so it was split up into two documents. In
deciding what to put where, I decided that making the first document be an
'engineers introduction to LISP' would provide a relatively coherent
document, one which would stand, and be useful, on its own.

Anyway, if someone (you?) would like to volunteer to write a 'users
introduction to LISP', that would be fine with me, but I'd like to keep the
'engineers' introduction to LISP' more or less as it is - and if you and the
WG think it would be better titled 'An Engineering Introduction to LISP", to
more accurately portray what it is, that would be fine with me.

	Noel