[cfe-dev] scan-build man page
kremenek at apple.com
Thu May 10 15:34:44 PDT 2012
On May 10, 2012, at 2:35 PM, James K. Lowden <jklowden at schemamania.org> wrote:
> All documentation is of two kinds: User Guide and Reference Manual.
> A UG walks you through how do things in some learnable order. It is
> read linearly. It starts with simple concepts and dismissable claims,
> and works through the process the creator's of the software supposed a
> user might take. It's indexed, and the user might have to backtrack.
> But it's fundamentally an exposition of why and how things are done.
> To some extent, it may explain the problem domain too.
> The RM is never read linearly except by dweebs and authors (possibly
> the same set). It is organized by feature and accessed by its
> index. It says what's true in as few words as possible. It's a "what"
> document. There's no place for why and how. The user is assumed to
> have read the UG, or at least to have the sense to follow the "read the
> UG" advice when the RM points him that way.
Great points. I suppose what we have on the website is somewhere in between a UG and RM, but not entirely both.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the cfe-dev