4 ms·

You seem to be describing the difference between a User Guide and a Reference Manual. Both are needed.

• crispyambulance 7y ago
  You're right that both of these forms are needed. There is, however, yet another category of documentation that is increasingly common and often becoming necessary in order to cope. I don't know if it has a formal name, but let's call it "context-sensitive" documentation. Some examples that come to mind are when you have auto-completion, "light=bulbs" or intellisense in IDE's, or -? options in the commandline. In situations where you are just trying to get stuff done, and you forget something trivial-- it's usually not some extremely complex edge-case, it's usually something mundane that you forgot because you don't often do that particular task everyday. In such scenarios, it's infuriating to have to skim through detailed man pages that cover every damn exotic use-case of the the command in alphabetical order, nor is it pleasant to pick up a user guide that starts from the most fundamental basics. There's room for documentation that sort-of reads you rather than the other way around. This kind of stuff has sometimes gotten a bad rap, since the days of "clippy" but it's getting better. In the IDE world, there was Resharper, and now even the Rosyln for dotnet has this stuff increasingly built in.