[cfe-dev] scan-build man page

[Ted Kremenek]

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...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120510/ffe4a09f/attachment.html>