Subject: Re: [lisp] Comments on draft-ietf-lisp-introduction-01

From: [email-masked] (Noel Chiappa)
Date: Tue, 23 Jul 2013 21:21:44 -0400 (EDT)

> From: "Michiel Blokzijl (mblokzij)" <[email-masked]>

    > I had at the time less than a handful of days to learn about LISP
    > ... and I still remember that it was.. let's say, "surprisingly
    > difficult". And, I think that we as the LISP community can do better (at
    > the time I hadn't read the lisp introduction draft).

Had you had this document available, would that have significantly improved
the situation?

    > I understand that comments to this draft are time-critical

Appreciated...

    > Despite me only having covered those, I see that my email is rapidly
    > approaching the <tl/dr> limits

Well, doing it in chunks will also keep the the reply size, etc down, so
good call on several fronts to go ahead as-is.

    > please don't take my criticism personally, it's about the working group
    > document, not about you.

None taken.

In return, please understand that I won't always agree with you - although I
will think carefully about your comments, and indicate _why_ I don't agree, if
I don't. (Anything I don't comment on, assume I agree with.)

    > I think this document is confused. It doesn't really know if it's an
    > architecture document, or an introductory text, or an introduction to
    > the architecture document.

Perhaps it would make things a little clearer if I explained that this
document is what used to be the first half of the 'LISP architecture
document'.  (the other part now being the 'Architectural Perspective'
document).  It got too long, so I chopped it in two along what I hoped was a
reasonable boundary.

As to the content of this one: to me, an architecture document has to _start_
by giving the reader a clear understanding of what the main pieces of the
system are, what they do, and how they interact. Oddly enough, the same is
true (IMO) of an Introduction. So, since I had to cover that ground
_anyway_...

    > I think that an architecture document and an introductory document serve
    > different audiences and purposes, even though there may be some overlap
    > in topics.

Which is why I chopped where I did: the 'Architectural Perspective' document
covers the stuff that's more 'architectury' (e.g. more about the properties of
the various abstract namespaces), and the stuff that could serve two purposes
(an introductory document, and the architecture overview part of an
architecture document) wound up in this one.

    > the main purpose of the introduction is to provide the reader an
    > overview of LISP and familiarise him/her with the main concepts,
    > emphasising understanding, perhaps even over technical precision.

Exactly; that's what the specs are for.

    > We should avoid having two very similar texts.

I can't imagine we'd ever with an 'Introduction to LISP', with this document
in existence - it would be 92% the same, and, as you impute, a waste of
energy.

    > ** I think the title "Architectural Introduction" adds to the confusion
    > here, and I think it would be better to just call this document
    > "Introduction to LISP", and aim for providing exactly that.

The names ("Architectural Introduction" and "Architectural Perspective") were
to indicate that they were two parts of a pairing. I'm not totally stuck on
the "Architectural Introduction", though, and if the WG would prefer to call
it just plain "Introduction to LISP", that would be OK with me. But there is,
I think, a good reason to retain the longer one - to tie the two together.

    > I think there's a lot of background material. I think we should aim for
    > "just enough" to understand the introduction to LISP, rather than a
    > comprehensive study of "LISP in the context of the history of the internet"

You're behind the curve! (See message from this morning, "Intro final content
questions".) That's getting moved to an appendix, so we can get straight to
the meat of LISP.

    > it looks like a VERY LONG introduction (37 pages if you print the HTML
    > page). I think introductions should be a bit shorter, and less
    > daunting. My first impression (with my LISP newbie hat on) is "Oh my
    > goodness, I need to read all that just to get an idea about LISP?".

I don't know how to fix that, except to make three documents (i.e. split this
one up), and I don't see any good/natural dividing line to do so. 

    > I know that the prefatory note says otherwise, but you don't see that
    > when you open up the HTML page and give it a quick scroll through.

I don't know how I could make it more prominent?

    > The design approach comes surprisingly late into the text (I'm not sure
    > this is even the right document for that)

My thinking in putting it there was that it's just before we get to the
'detailed look at LISP operations' content - and it's only when you get to
that content that you really need it.

Actually, it used to be a much longer section, almost all of which I moved to
the other document to keep the size down on this one, and because it's not
absolutely necessary to have it here.

    > Here are some sections I don't think are necessary for the introduction
    > ... mostly because they sound like they're going into the nitty gritty
    > detail that should be part of main protocol specs:

There are no packet formats, no detailed algorithms - just coverage, at a
_high level_, of more stuff than just the brief descriptions in section 6.

    > 4.4.  Interworking With Non-LISP-Capable Endpoints (maybe)

That's a critical thing about LISP - that it _can_ interoperate usefully with
non-LISP sites. 3 short paragraphs is appropriate to talk about that.

     4.5.  Security in LISP [or at least move it closer to the end]

I think saying something about security in LISP is important in a "LISP
Overview". That section was just written, so it probably can use some
polishing, but again, 4 short paragraphs don't sound like an inappropriate
treatment. (The section in the 'Perspectives' document which talks at more
length about LISP's security philosophy, and more about how it applies in
various places, takes up ~30 paragraphs - and it's not fully written.)

     9.2.  UDP Encapsulation Details ("details")

Again, 4 paragraphs. No formats, no specs, just a short, high-level discussion
of how it works. (Maybe you should have read these before creating this list?)

    > I'm not saying none of these should be mentioned, but I don't think each
    > of them warrant a section of their own in an "introduction" document. I
    > think things can be summarised a bit more to convey the main points.

Look, if you want a 10-page 'Brief Introduction' document, one which differs
significantly from Sections 3-6, since it's intended that people who want a
brief introduction can read just those, and stop), please feel free to write
it.

I'm producing an "Architectural Introduction", and I feel the modest level of
detail in all those sections you mention is needed. Most of them are really
short - a couple of short paragraphs, almost all of them. And the content in
all of them is very high-level.  The number of them is because that's how it's
all organized in my brain - broken down like that. I'm trying to convey that
understanding on paper.

    > There is lots of stuff in brackets, which looks like it might be too
    > important to be ignored, so perhaps it's not all suitable to be in
    > brackets?

That's always been an artifact of my writing style. Everything in my brain is
connected to everything else, and those parenthetical asides are how I attempt
to convey those connections... If you have specific suggestions on how to
re-word some, I will take a look at them.

    > I would be inclined to say "IPv4 and IPv6 internetwork", I think that,
    > while technically correct, IPvN is a less often used term. ... You could
    > also just say "IP".

Given that the abstract is _already_ too long, the former isn't really in the
cards. But "IP" works for me.

    > I'd also drop the * 'system', as I think an internetwork is a system
    > already?

You may understand that, but I'm not sure everyone does... :-) Hmmm... if I
drop it, it feels stilted (unless I re-word, and then it's even longer).

    > What do you mean with 'currently intermingled in IPvN addresses'?  Do
    > you mean that location and identity are currently both expressed in IP
    > addresses when using LISP?  Or do you mean that in the current IP world,
    > both location and identity is expressed with 1 IP address?  I guess the
    > latter, but I don't think it's particularly clear.

I have changed "currently" to "previously" - that should make clear that that
statement doesn't refer to LISP.

    > If this was wikipedia or an academic paper, I'd tag that with "citation
    > needed".

It's the _abstract_. No cites in most abstracts... :-)

    > Spello: "prefatory" is suggested by Google.

And I should care what Google thinks...? But I admit "prefaratory" is a bit
old-fashioned, so we'll go with "prefatory".

    > I don't think it's necessary to provide a very detailed understanding of
    > the entire system as part of the introduction though

You're confused. The 'details' here aren't that detailed. Try reading,
e.g. section 9.6, "Security of Mapping Lookups". That covers most of a 20-page
spec in three, count them, three paragraphs.

If you think that's "detailed", you have a very strange definition of
"detailed".

    > after all, that's what all the other documents are there for

See above.

Speaking of "other documents", here's an exercise for you.

List all the documents which have a significant amount of content which is
covered here. My list looks like this:

  RFC 6830 - The Locator/ID Separation Protocol (LISP)
  RFC 6831 - The Locator/ID Separation Protocol (LISP) for Multicast Environments
  RFC 6832 - Interworking between Locator/ID Separation Protocol (LISP) and Non-LISP Sites
  RFC 6833 - Locator/ID Separation Protocol (LISP) Map-Server Interface
  RFC 6834 - Locator/ID Separation Protocol (LISP) Map-Versioning
  ID.draft-ermagan-lisp-nat-traversal
  ID.draft-ietf-lisp-ddt
  ID.draft-ietf-lisp-deployment
  ID.draft-ietf-lisp-sec
  ID.draft-meyer-lisp-mn
  ID.draft-saucez-lisp-impact-01
  [Iannone]
  [Kim]
  [CorasCache]
  [Jakab]
  [Saucez]

Now, add up the lengths of all those documents. Next, what %-age of that is
this document?  My guess is that it's about 6%, at most. So instead of people
having to read hundreds upon hundreds of pages to get a moderately detailed
understanding of LISP (although admittedly if they read them all, they'd have
an extremely detailed understanding of LISP), they have to read 30-odd. (Less
than that if they only want a brief intro, in which case they can stop at
Section 7, as discussed in the preface.) I think that's not bad.

    > I think a huge intro will just scare people off.

Again, if you think there's some use/benefit for a 'Brief Introduction to
LISP' (briefer than only reading down through section 6 - maybe 7, if they
want to see some simple examples), please write one.

    > I'm not sure an unusual structure helps understanding.

In a Deep Purple live recording ("Made in Japan", if anyone cares), there is a
classic line: "Can I have everything louder than everything else." (He's
talking about the monitors on the stage.) Similarly, I would _like_ to 'talk
about everything before everything else'. But I can't. So I have two choices.

1. I can pick a piece, and talk about it first, in great detail, before I talk
about anything else. (This is what protocol specs usually do.) To me, at
least, that is unlikely to lead quickly to a good overall grasp of what the
systems major functional units are, what they do, and how they
interact. (Which is, after all, what I said I'd like to see in an architecture
document.) How can the reader understand well the interaction with some other
subsystem, when they haven't read anything at all about that subsystem yet?

2. Describe the entire system _very briefly_ at a very high level; then, when
I next talk about some piece in a little more detail, the reader has a mental
framework/model of the 'big picture' into which they can slot the details of
that particular piece. Repeat.

Given those two choices, I went with 2. 

    > Have you given this to someone new to LISP and asked them how much they
    > understood?

A while ago. Not with recent versions.

    > I think that, apart from the first paragraph, the background section
    > doesn't actually further the understanding of the document, as the bits
    > in it are not necessary to understand LISP.

Which is why I had previously decided to exile most of it to an Appendix (see
reference to previous message, above).

    > I think however that it would be more useful to briefly introduce the
    > location/id split by looking at an example:

In general, I personally hate examples, but I guess for most people they ar
useful, so I will add one when I refactor that section and exile most of it.

    > Please could you point out exactly which bit of RFC6115 supports the
    > above statement, especially the first sentence? Maybe I missed it.

It's in Section "1.2.  Areas of Group Consensus", point 9:

 "The Research Group has rough consensus that separating identity
  from location is desirable and technically feasible."

Do I need to go to that level of detail in the cite? IETF RFC's generally
don't do page number citations.

    > I think this statement would require regular updating as LISP matures,
    > so I'm not sure it's suitable for a static RFC.

I actually am very sympathetic to the 'long lifetime' goal for documents like
this, and I have tried to attain that with this one (and that's why e.g. there
are no packet formats here).

But I'm not sure this particular statement is problematic: it says LISP is "a
moderately mature system" - from where it can only go forward, not backward,
right? So it can only become "very mature", and I don't see that as that big a
difference.

And put against that the value of the point I wish to make: that LISP is not a
paper exercise, but something with real experience behind it.  (Although that
may be a less critical point to make now than it was, say, 2 years ago.)

    > I think the History section should go into an appendix. We want to make
    > it as easy as possible for newbies to pick up and understand LISP, and
    > having less text between them and LISP means newbies are less likely to
    > loose interest.

Couldn't agree more, etc, etc.

    > I think this paragraph doesn't add much value.
    > It's 7 lines explaining why the next 8 lines are there

Exactly.

I'm trying to explain to the average reader WTF a document called
"Introduction to LISP" _starts_ by talking about "Deployment Philosophy".
Which might seem like a bizarre, nay, dumb, choice, to the average reader. I'm
trying to show them why it's there, to give them some sense that the writer is
not hopelessly confused.

    > So that sentence there the real content of this whole section?

There are some very major IETF failures^H^H^H^Hefforts that didn't appear to
have considered that important. Which is a good part of why I wanted to say it
so forcefully.

    > Considering the fact that there are more sections dealing with
    > deployment, I think some merging and cutting needs to happen.. I'm thinking
    > about 3.1-3.3., and 8. Design Approach

Maybe you should have read section 8 first? There's almost nothing there, just
a reference to the other document.

And I've already explained why 8's down there, not further up. (If I moved it
up, it would be in the way of getting to the initial description of LISP. That
would not be good, right?)

    > I think it's fine to say something like ...
    > ... [this is just a sketch of the argument I'm trying to make, not a
    > final wording suggestion]

I'll have to ponder this when I'm fresher. Perhaps I can improve that section
some.

    > I'd cut the section "3.3.  'Self-Deployment'"; I understand that a
    > snowball effect is very desirable, but I'm not sure it furthers any
    > argument at this point in time.

Again, a number of other major IETF design efforts have clearly missed this
point, so I think it's worth stating it.

    > This whole section is basically useless. It's only piece of real content
    > is the reference to [Perspective].

I'll see if I can trim it a bit more. I don't think it's appropriate to just
say 'The design philosophy is covered in detail in in [Perspective], Section
"Design".'

	Noel

---

From: "Michiel Blokzijl (mblokzij)" <[email-masked]>
Date: Wed, 24 Jul 2013 12:49:14 +0000

Hi Noel,

First of all, thank you for taking the time to read through my long set of
comments!

Reading your reply, I think that we just have very different expectations
of the introduction document. I'll finish going through your draft since
I've started it now.

Here are some of the main points I picked up from your reply:
- document split & titles, extending the abstract, sections 3-6, potential
derived/new 'brief introduction to LISP' => I'll get back to this when
I've gone through those sections
- the [necessary] level of detail: I think the document currently provides
a reasonably comprehensive but high-level overview of LISP, rather than an
introduction, if that makes sense. I'll get back to this too.

I'll add some more comments inline ([M]), but I think it's best if I
finish going through the document before we get into too many detailed
discussions :-)

Best regards,

Michiel

>I don't. (Anything I don't comment on, assume I agree with.)

[M]: sounds good, thanks!

>questions".) That's getting moved to an appendix, so we can get straight

[M] Sorry about that! I'm glad you came to the same conclusion.

>I don't know how I could make it more prominent?

[M] By having a shorter document.. :)

>that content that you really need it.

[M] I see.

>absolutely necessary to have it here.

[M] Ok. I think as it stands it doesn't actually add much, but let's
discuss that later.

>Given those two choices, I went with 2.

[M] I don't think there's anything fundamentally wrong with approach 2,
assuming you don't recurse ad inifinitum. However, I

>A while ago. Not with recent versions.

[M] Now you've made us all curious, what did they say? :)

>don't do page number citations.

[M] Ok, that's fine, thanks for clarifying this!

>right? So it can only become "very mature", and I don't see that as that

[M] I wouldn't say that the statement is 'problematic'. Maybe it's worth
tying this statement to "the time of writing", and say it's constantly
maturing - just to avoid people in the future dismissing LISP as a
solution to a problem requiring a "mature" solution.

>may be a less critical point to make now than it was, say, 2 years ago.)

[M] It's a good point.

>trying to show them why it's there, to give them some sense that the

[M] I understand.. But when you start having more justifying text than
actual content you start to wonder whether it might be easier to just "say
it"? :)

---

From: Dino Farinacci <[email-masked]>
Date: Wed, 24 Jul 2013 09:51:06 -0700

> I think, a good reason to retain the longer one - to tie the two together.

I would vote for "Introduction to LISP". But if that is decided, the document needs to be brief, to the point, and reference other documents (the RFCs and the Architecture Perspective document).

But all in all, I have always been in favor of less documents. Because once you start with details, it is easy to go real deep and that is what the protocol documents are for.

Dino