Re: [lisp] Intro doc - to split, or not to split

[Fabio Maino <[e-mail]>]

Noel,
sorry for the delay.

In my opinion splitting may be better.

The way I read the charter, we're asked to provide an intro to LISP that 
would guide the reader through the various docs of the LISP 
specification. I believe the doc, up to section 7, does a pretty good 
job in addressing that requirement.  This may also speed up the review 
process, and moving the document forward.

Did you consider including part II in the perspective document? It seems 
that the more details provided there may fit the interest of a reader 
willing to know more about LISP.

One possible way to do the integration would be to reuse most of section 
7 from the current doc. You could use that as a preamble, where you 
describe a packet's processing, while you refer to the introduction for 
a more formal introduction of terms and definitions.
That would lead to the subsequent sections, and then to the actual 
content of the perspective doc.

Thanks,
Fabio




On 10/5/13 4:05 AM, Noel Chiappa wrote:
> At the just-concluded Interim WG meeting, there was a certain amount of
> discussion of the idea of splitting the Introduction document into two roughly
> equal-length document (the split being just after 'Examples').
>
> The basic rationale for splitting it was that it's too lengthy (and detailed,
> towards the end) a document to give to someone who just wants to know
> 'something about LISP', but that the first part is not a bad introduction to
> LISP to those who want to know 'something about it'.
>
> (Albeit that the focus is 'what are the main moving parts _inside_ LISP, and
> how do they interact', rather than 'this is what LISP can do for you', or any
> number of other potentially useful documents).
>
> There are good points both ways (two documents, and one), and we had a certain
> amount of indecision about what to do.
>
> Since the document is _already_ structured as 'a shorter adocument within a
> larger one' (with the explicit notation that people can read just the first
> part, if they want a 'brief intro to LISP'), it seemed a natural move to
> _actually_ split it in two. Other than a certain amount of editorial work
> (inter-section references would have to be fixed), it needed little work to
> accomplish.
>
> So we agreed to do it.
>
> Hoever, on thinking about it a bit, I decided that while that would result in
> a perfectly find stand-alone first document, the second would be problematic.
> To use an analogy I came up with, it was rather like a decapitated body - it
> was so obviously the second part of something, and there was no good way to
> make a standalone document out of it. (Imagine the title... "Intro: Part II"?)
> The only solution seemed to be to put the head back on...
>
> People seemed to understand, and agree, that there was a problem with the
> second half as a stand-alone document, so we then decided we'd leave it as
> one.
>
> We further decided that we'd emphasize the two-part nature of the document by
> formally splitting it into "Part I" and "Part II".
>
> What do people think of this? Is everyone happy with it? If someone would
> prefer two, can they see a way to make a viable document out of the second
> half? Speak!
>
> 	Noel
> _______________________________________________
> lisp mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/lisp