There are two basic kinds of documentation: user's guide and reference documentation.
Both can contain sections on the overall design to avoid repetition but will describe it from different standpoints.
(Some companies also recognize overview as a separate kind, see below.)
Reference documentation lists, diligently and accurately, the entirety of the product's public interface: what each switch and parameter means, what input is considered valid and what is returned in each case etc.
- Note the word public interface: its primary goal is to specify which details of the observed behavior are officially guaranteed and thus can relied upon. (Stating or implying by omission that everything else is implementation details, subject to change and break without notice.)
- Also note the word "entirety". The primary selling point of a reference is its completeness. If it's not in the reference, it doesn't (officially) exist. If I've read a reference on a topic, I can be sure that I now know everything on that topic and there'll be no nasty surprises.
- So, even though a reference can be used as a learning material, its primary use case is to fill in the gaps.
Since design principles directly manifest themselves in the structure and organization of the public interface, a reference documentation can contain overview sections on parts and aspects of the product interface and behavior before listing their details (if only to avoid repeating them in entries for individual APIs).
- Again, the focus is the public interface, so the explantions shall focus on the user-visible details critical to understanding the product's organization and behaviour, and technicalities not important for that can be omitted or hand-waved.
A User's guide purpose is rather to demonstrate how the product's authors envision using the public interface to solve practical problems and/or classes thereof: intended usage patterns, typical general problems and proposed solutions (problems local to specific APIs seem to rather belong in their reference entries).
A user's guide is intentionally incomplete, giving only the "big picture" and key pointers and leaving it up to the reference to elaborate on details.
User's guide can also have overview text, but the focus of the overview here is the usage patterns: what is supposed to be called after what, from what places etc.
- note the word supposed. This is a recommendation: "This is the way that we intend to be the preferred one". What can (or cannot) be called from where outright is reference documentation domain.
Some companies, e.g. Microsoft, segregate the highest-level overview into a separate kind of documentation. In many place in MSDN, you would see a section on X divided into: "About X", "Using X" and "X reference".
As you can see, a user's guide and reference complement each other, cover different topics and explain things from different standpoints. Though the guide is more beneficial to the user in the short run while reference documentation in the long run.
Since reference is complete, it's "superior" to a user's guide in that any information that would be present in the latter can be inferred from it -- though at the cost of a steeper learning curve.
OTOH user's guide is much, much smaller and less taxing to maintain, especially if the interface changes quickly. The downside is your users never being sure if what they are trying to do other than the few examples you gave is supposed to work or not, what syntax is permitted where etc -- resulting in massive waste of their time.
man pages are a classic example of reference documentation. Some man page authors (e.g. rsync) tried to add user's guide sections -- and by doing that made it harder to locate the necessary reference material.
