[Nfd-dev] comments for the nfd doc

[Junxiao Shi]

20140622 NFD conference call discusses the big picture comments from Jeff
Burke.


On Sat, Jun 21, 2014 at 12:00 AM, Burke, Jeff <jburke at remap.ucla.edu> wrote:

>
> Big picture comments:
>
>
>
> 1.     I think the document could be re-organized in a simple way to
> provide a clearer high-level view of how the forwarder functions first, and
> then dive into the details. While starting with Faces makes sense from a
> bottom-up perspective, a critical thing to understand first may be how NFD
> processes packets, and what the various modules/abstractions are.  This
> might be accomplished by moving the pipelines section earlier or by
> expanding the introduction to talk about packet processing, the
> relationship between NRD / NFD, etc.
>
We should expand the introduction: pick something from later sections and
put in introduction.
Contents in later sections should not be reduced.

We can describe how a packet flow through the system: how an Interest/Data
packet flow through the system (data plane); how a ControlCommand flow
through the system (including the RIB Daemon).
Within this text, we should introduce all the major concepts.

>
>
> 2.     More generally, it would be nice if the document was re-organized
> to reduce the number of forward references needed to understand something
> in detail, and grouped discussion of functionality together.  (E.g.,
> Strategy, Strategy Choice Table, Strategy Manager could all be in a
> strategy section, rather than spread out, if the notion of managers and the
> Name Tree are introduced beforehand.)
>
>
>
> a.     For example, the strategy choice table structure section is hard
> to read / understand without reading about strategy first. While a forward
> pointer works, it would be better if the strategy section came first.
>
>
>
> b.     Similarly, high-level abstractions used repeatedly that are
> relevant to the way the code is organized, e.g,. the notion of “managers”,
> should be introduced briefly at the beginning, rather than relying on
> forward references.   Then, you could group the description of each manager
> with what it manages… the FIB manager description could go in the section
> about the FIB, the strategy manager in the section about strategy, etc.  I
> think this would make these various things easier to grasp quickly.
>
This cannot be completed within 0.2 timeline, but we can consider it for
next version.

>
>
> 3.     I would highly recommend increasing the terseness / consistency of
> terminology.  E.g., the terms callbacks and triggers are used in the early
> part of the document, but there is a whole section on the “event system” –
> what is the difference between a trigger, event, timer, signal (p7), and
> callback?  Can the number of terms be reduced?  It’s not that the
> relationship is particularly complicated, but it creates noise for the
> reader unnecessarily. If the terminology does not reflect functional
> differences, it should be collapsed; if it does, it should be explained
> more clearly.    Other examples are distinguishing between Internal and
> Local (Internal doesn’t show up in the table in 2.1); non-local vs. remote
> and peer, etc.  Similarly, there is a “face system” but a “tables module”…
> What is a system vs. a module?   Namespace vs. a prefix?   Operator vs.
> user vs. administrator (p40) vs. application vs. developer?  Streamlining
> terminology may greatly improve readability for the first-time reader.
>
Agreed.

>
>
> 4.     Consider also putting security earlier, and working more security
> information into the other sections over time.   Also, the notion of
> /localhost and /localhop are worked with throughout as a key concept, but
> not discussed in the security section
>
We should create a "scope control" page on NFD website, which becomes part
of protocol.
This document is then cited in Developer Guide.

>
>
> 5.     A future work / open issues section would be helpful.
>
This does not belong in this document.
Future work and open issues are on Redmine. We should create a webpage on
NFD website.

>
>
> 6.     Utilities (6.2) should likely be last in the document, and
> probably integrated with Section 9.
>
No. These classes are internal to management. They are not common services.
We shall change the title to "Utilities for managers".

>
>
> 7.     As with any early draft, the document probably needs a single
> editor to do a pass to make the language more consistent and simpler.  “The
> purpose of the channel abstraction is to encapsulate the functionalities
> needed to accept incoming connections or tostart outgoing connections, and
> to create a face when the connection attempt is successful.”  (p7) =>
> “Channels start outgoing connections and accept incoming connections.  They
> create Faces for successful connections.”
>
Agreed.

>
>
> 8.     Diagrams could be made more consistent, and you may want to
> allocate space based on their complexity.
>
>
>
> a.     E.g., Figure 2 is really useful and has a lot of information, but
> is only given the same space a Figure 7.
>
>
>
> b.     In fact, having more diagrams like Figure 2 per section would be
> very helpful.
>
>
>
> c.     The visual overview of all pipelines (Figure 10) is critical and
> probably needs to be redrawn to be clearer (fewer colors, stronger lines,
> etc), have a key (what are yellow boxes) and perhaps give more detailed
> information.
>
>
>
> d.     There are too many visual styles of diagrams, but this could be
> fixed later.
>
We'll try to improve if time permits.

>
>
> 9.     Things that are usually not NDN-like, in particular channels and
> hosts, should have some bit of explanation that explains why these
> abstractions or terms are used.
>
No. They refer to the physical world: communication medias and computers.

>
>
> 10.  There are a few places where there is discussion of a use condition
> (e.g., “The FIB is expected to be relatively stable” p10) that are
> problematic, as they do not 1) provide evidence, explanation, or citation
> for the statement, 2) explain what it actually means in technical terms, or
> 3) explain why it’s relevant to what’s being read or what was designed. In
> the FIB example, would a vehicle’s FIB in a highly dynamic environment be
> considered “relatively stable” or not?  Etc.  These types of statements
> should be removed or explained in terms of the three aspects above, if
> possible.  They a little distracting because they seem to beg the question
> rather than clarify the design strategy as intended.
>
Junxiao's reason for writing this is to provide a direction for
optimization. eg. "FIB is relatively stable" means FIB shall be optimized
for faster lookups instead of updates.
 However, the writing is vague and should be improved. eg. "On wired
Internet, frequency of FIB updates is much less than FIB lookups, so FIB
should be optimized for lookups rather than updates.".

>
>
> 11.  When describing specific relationships, “Management calls
> Cs::setLimit”, perhaps it is better to say which manager(s) specifically?
>  Management is used generally several times
>
Agreed. This can be changed as "Management changes ContentStore capacity
via Cs::setLimit".

>
>
> 12.  Summary figures like Fig 18 could perhaps come earlier
>
There's no need to distinguish between applications and routing protocol.
There's no need to distinguish between "self registration" and "routing
update". Change them to "RIB update", and the arrow shall be curved to
point to RIB Daemon.
RIB Daemon can point to NFD with "FIB update".

>
>
> 13.  Should there be timing diagrams (p36) for other components besides
> the RIB manager?
>
No. We shouldn't apply timing diagram to other sections.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.lists.cs.ucla.edu/pipermail/nfd-dev/attachments/20140622/2e507390/attachment.html>