NFD

From: Jeff Burke

Date: Mon, 18 Aug 2014 15:51:26 +0000

Subject: [Nfd-dev] NFD documentation comments

Hi NFD team,

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. :)

Please take/ignore as you will. I hope the comments are helpful.

cheers,
Jeff

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.

• 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:
  On the web: "A more recent version of this document may be available on NFD Wiki."
  On the wiki: "A more recent version of this document may be available on NFD Homepage."

• 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.

• 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 seems 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.

• Not sure that README.md and docs/README.rst should be different. ?

• 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.

• 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.

• 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".

• 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).

• 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 after what appear to be build instructions on all platforms. This should be re-arranged or at least have different titles to be more clear.

• Each document in index.rst should have a short explanation of what people will find there / why they should go there. For example, "Getting started" is how to install, whereas README provides project background, etc.

• Consider having a pointer to RELEASE NOTES in the README, and certainly in index.rst.

• 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?

• 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.

• 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.

• 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.