Project

General

Profile

Actions

Task #1905

closed

Various NFD documentation suggestions

Added by Jeff Burke over 9 years ago. Updated over 9 years ago.

Status:
Closed
Priority:
Normal
Assignee:
-
Category:
Docs
Target version:
Start date:
Due date:
% Done:

100%

Estimated time:

Description

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.

Actions #1

Updated by Anonymous over 9 years ago

  • Status changed from New to In Progress
  • Assignee set to Anonymous
  • Target version set to v0.2
Actions #2

Updated by Junxiao Shi over 9 years ago

  • Description updated (diff)
  • Category set to Docs
  • Start date deleted (08/22/2014)
Actions #3

Updated by Anonymous over 9 years ago

  • Status changed from In Progress to Feedback
  • % Done changed from 0 to 70

The initial pass is in. Right now, I'm focusing on moving the content around as suggested and leaving any additions to future commits (possibly by more knowledgable authors, e.g. security stuff).

Is it ok to move the FAQ to the wiki? I think this is a good idea.

I'm ok with README-dev.md as is. It contains a number of things, like the license boilerplate, that are useful to developers. I agree that users may need to run the unit tests, but maybe we should add a section on one of the NFD website pages for "reporting problems".

Actions #4

Updated by Alex Afanasyev over 9 years ago

Steve DiBenedetto wrote:

Is it ok to move the FAQ to the wiki? I think this is a good idea.

No. I'm strongly against such action. All FAQ items should be part of the NFD internal documentation and go through normal review process. FAQ for different versions could be different.

Actions #5

Updated by Jeff Burke over 9 years ago

After hearing the motivation, I agree with Alex on this one, but I guess I got a little confused about what was encouraged on the wiki because some specifications (NDNLP, management, etc.) seem to have their canonical version there as opposed to the internal documentation.

Actions #6

Updated by Alex Afanasyev over 9 years ago

For me, wiki is to develop and provide initial thoughts, updates, etc.

We should move most of the protocols definitions and other stuff to the internal docs at some point.

Actions #7

Updated by Alex Afanasyev over 9 years ago

  • Status changed from Feedback to Closed
  • % Done changed from 70 to 100
Actions

Also available in: Atom PDF