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

From: [email-masked] (Noel Chiappa)
Date: Sat, 5 Oct 2013 07:05:13 -0400 (EDT)

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

---

From: Dino Farinacci <[email-masked]>
Date: Sat, 5 Oct 2013 07:25:17 -0400

I vote for the Part I/II option in one document. 

Dino

> On Oct 5, 2013, at 7:05 AM, [email-masked] (Noel Chiappa) wrote:
> 
> _______________________________________________
> lisp mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/lisp

---

From: Paul Vinciguerra <[email-masked]>
Date: Sat, 5 Oct 2013 17:18:24 +0000

+1.  

Add parts

Since the document targets multiple audiences, the heading additions let the reader chose the content relevant to their role.   

Paul
________________________________________
From: [email-masked] [[email-masked]] on behalf of Dino Farinacci [[email-masked]]
Sent: Saturday, October 05, 2013 7:25 AM
To: Noel Chiappa
Cc: [email-masked]; [email-masked]
Subject: Re: [lisp] Intro doc - to split, or not to split

Dino

---

From: Fabio Maino <[email-masked]>
Date: Tue, 15 Oct 2013 11:09:14 -0700

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

---

From: Edward Lopez <[email-masked]>
Date: Wed, 16 Oct 2013 12:11:07 +0000

If you split the documents into two, I'm assuming you would need to include the necessary redundancies and cross referencing needed for the two documents to make sense.  It seems to me that this is a lot of effort just to put a logical easy/hard split in the current document, and that the audience for an RFC would prefer a single document.  I think that lightweight LISP documentation will ultimately be developed by those entities developing LISP-enabled products  (Cisco already covers their implementation in infinite detail).

To me, keeping the single document makes the most sense.

> Since the document targets multiple audiences, the heading additions let the reader chose the content relevant to their role.   

***  Please note that this message and any attachments may contain confidential 
and proprietary material and information and are intended only for the use of 
the intended recipient(s). If you are not the intended recipient, you are hereby 
notified that any review, use, disclosure, dissemination, distribution or copying 
of this message and any attachments is strictly prohibited. If you have received 
this email in error, please immediately notify the sender and destroy this e-mail 
and any attachments and all copies, whether electronic or printed.
Please also note that any views, opinions, conclusions or commitments expressed 
in this message are those of the individual sender and do not necessarily reflect 
the views of Fortinet, Inc., its affiliates, and emails are not binding on 
Fortinet and only a writing manually signed by Fortinet's General Counsel can be 
a binding commitment of Fortinet to Fortinet's customers or partners. Thank you. ***