<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif;">
<div>Hi,</div>
<div>Submitted as Task #1905.</div>
<div><a href="http://redmine.named-data.net/issues/1905">http://redmine.named-data.net/issues/1905</a></div>
<div>Jeff</div>
<div><br>
</div>
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<div style="font-family:Calibri; font-size:11pt; text-align:left; color:black; BORDER-BOTTOM: medium none; BORDER-LEFT: medium none; PADDING-BOTTOM: 0in; PADDING-LEFT: 0in; PADDING-RIGHT: 0in; BORDER-TOP: #b5c4df 1pt solid; BORDER-RIGHT: medium none; PADDING-TOP: 3pt">
<span style="font-weight:bold">From: </span>Jeff Burke <<a href="mailto:jburke@remap.ucla.edu">jburke@remap.ucla.edu</a>><br>
<span style="font-weight:bold">Date: </span>Mon, 18 Aug 2014 15:51:26 +0000<br>
<span style="font-weight:bold">To: </span>"<a href="mailto:nfd-dev@lists.cs.ucla.edu">nfd-dev@lists.cs.ucla.edu</a>" <<a href="mailto:nfd-dev@lists.cs.ucla.edu">nfd-dev@lists.cs.ucla.edu</a>><br>
<span style="font-weight:bold">Subject: </span>[Nfd-dev] NFD documentation comments<br>
</div>
<div><br>
</div>
<blockquote id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE" style="BORDER-LEFT: #b5c4df 5 solid; PADDING:0 0 0 5; MARGIN:0 0 0 5;">
<div>
<div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;">
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
Hi NFD team,</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
Yesterday I tried to methodically follow the directions for installing NFD on a few machines, and wanted to share some comments on the documentation. I have installed it in the past, but tried to forget what I remembered. :) </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
Please take/ignore as you will. I hope the comments are helpful.</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
cheers,</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
Jeff</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
--- </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
Once I figured out where to look, the docs are pretty easy to figure out and things build/install smoothly. Congrats! The main confusing thing is that there are several candidate starting points (all of which I ended up needing), and replication of documentation
on the Wiki, github source distribution, website. </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- I'd suggest not duplicating pages on the Wiki and the Web. It leads to confusion and inconsistencies. For example, the Getting Started with NFD has this circular reference:</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<div>
<div>
<div>On the web: "A more recent version of this document may be available on NFD Wiki."</div>
<div>On the wiki: "A more recent version of this document may be available on NFD Homepage."</div>
</div>
</div>
<div><br>
</div>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- The pointer at the top of README.md should more directly address the person who wants to get the package installed, ie., "For complete documentation, including step-by-step installation instructions, go to NFD's homepage." If this change is made, then I'd
suggest everything after the overview in the README can be in the installation instructions rather than the README. This would reduce redundancy.</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<div><br>
</div>
<div>
<div>- Ideally, I think that all documents/sites/etc. should emphasize a single starting point for working practically with NFD – either index.rst or the README. They should also point to the named-data web (rather than in Github, say). It <i>seems </i>like
one should be able to open and navigate the docs on github, but this doesn't always work. I'd suggest that people browsing on github be more clearly directed to the named-data.net starting index page or their local docs for NFD installation. </div>
</div>
<div><br>
</div>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- Not sure that README.md and docs/README.rst should be different. ? </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- There is information about binaries spread across many places: the README.md, the FAQ, index.rst, and "Getting Started", the latter of which is described as source code (not binary) instructions by the README.md. Perhaps this could be consolidated to
a single location and referenced as needed. </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- Also, there is discussion of platform build experience in "Additional Information" that would probably be more useful in the "Getting started" page near the source instructions. </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- There is an INSTALL.rst file, which is really source build instructions. It is not nearly as useful as "Getting Started with NFD". I'd suggest the two files should be combined and one eliminated... as "INSTALL" is the obvious place to look, but incomplete.
Or, if you want to keep them separate, the INSTALL file needs to end with a pointer back to Getting Started to continue configuration, and perhaps start with proper clone instructions, etc. The INSTALL document should also be titled something more descriptive
like "Building NFD from source". </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- The Wiki needs to be more prominently linked in the documentation, especially the README, as the place to do to get packet format and protocol information (if this is indeed the right starting point). </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- The documentation often needs to be read-ahead to be understood. This should be corrected where possible. For example, the "Getting Started with NFD" document sends you to install ndn-cxx and NFD according to instructions on other pages, but further down
gives you the correct clone instructions. The clone instructions should be given first, then the reader send to the pages to follow the install instructions. Another example is the MacOS X build instructions (including the PKG_CONFIG fix), which come <i>after </i>what
appear to be build instructions on all platforms. This should be re-arranged or at least have different titles to be more clear.</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div><font face="Calibri,sans-serif">- Each document in index.rst should have a short explanation of
</font><font face="Calibri,sans-serif"><i>what people will find there / why they should go there</i>. For example, "Getting started" is how to install, whereas README provides project background, etc. </font></div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- Consider having a pointer to RELEASE NOTES in the README, and certainly in index.rst. </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- The FAQ document is sort of a catch-all. To me, all of the answers really should be in the appropriate sections of documentation, rather than in a FAQ list without an index, but I understand its current purpose while the documentation is still in its infancy.
In particular, though, "How to configure NFD security" should be the stub of its a separate document on NFD security configuration. Also, I wonder if, though, the FAQ should be a Wiki page, so it is more easily community-editable? </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- The default security actions that are performed by the binary installations should be described (and motivated) so they can be duplicated by those doing source installs. And/or, scripts should be provided to do the same things in the source installs. Further,
though NFD ships with no security configuration, it does by default create identities the first time it is run. This should be better described. </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- Unit tests are not only needed by NFD developers, they are of interest for anyone wanting to check for problems building this new code on their hosts. (I had to run them to help narrow down a problem with EthernetFace on my machine.) The unit test installation
instructions should be included in the main installation instructions. Since there is nothing else of consequence in README-dev, I think that file should be removed for now, and a pointer provided in the README to the NFD wiki, which I'm sure contains more
detailed and up-to-date information for developers. </div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
- The test producer and consumer distributed with the ndn-cxx library can't be run without NFD. The docs should mention this even though the apps throw an error.</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
<div style="color: rgb(0, 0, 0); font-family: Calibri, sans-serif; font-size: 14px;">
<br>
</div>
</div>
</div>
_______________________________________________ Nfd-dev mailing list <a href="mailto:Nfd-dev@lists.cs.ucla.edu">
Nfd-dev@lists.cs.ucla.edu</a> <a href="http://www.lists.cs.ucla.edu/mailman/listinfo/nfd-dev">
http://www.lists.cs.ucla.edu/mailman/listinfo/nfd-dev</a> </blockquote>
</span>
</body>
</html>