Updating high-level review guide principles about dev_guide HOT 3 CLOSED

In #10 I had written "@noamross' post on how to review". Is this post still a project? If it isn't, I can use the points you mention above, I just don't want to step on anyone's toes. 😸

from dev_guide.

@noamross could you clarify what you mean by "Documentation should use the principle of multiple points of entry"? Your other points have made their way to chapter 1.

from dev_guide.

As I recently wrote in the rcites review, where I phrase it slightly differently:

Remember the principle of first entry - any piece of documentation may be the first encounter the user has with the API, data source, or even the CITES treaty/organization.

Basically, this means the README, the top-level package docs, vingettes, websites, etc., should all have enough information at the beginning to get a high-level overview of the package and the services/data it connects to, and provides navigation to all the other relevant pieces of documentation. I think this is especially important because of the number of websites out there like Rdocumentation, which suck up and aggregate various types of documentation in ways you don't control.

from dev_guide.