[cfe-dev] scan-build man page

[TP]

On Thu, May 10, 2012 at 1:02 PM, James K. Lowden
<jklowden at schemamania.org> wrote:
> If test cases and examples are many, I would say you're describing
> a user guide more than a reference manual.  As long as you have two
> documents, the man page can be terse because "how" is explicated in the
> user guide.
>
> I could make a case for a user guide in -mdoc format.  It would
> be easy to view in a terminal, and PDF is very pleasant for linear
> narratives (not to mention printing).
>
> But DocBook gets the job done, too.  It has more verbose input and a
> bigger toolchain, but you get very nice HTML.  A single DocBook document
> *can* be rendered as HTML and Postscript/PDF, but it takes some skill
> and willingness to particularize parts of the source with escapes for
> intended targets.  A project the size of clang can probably cope with
> those issues.

Jacob Kaplan-Moss in "Writing great documentation" talks about four
types (Tutorials, Topic Guides, Reference, Troubleshooting) and levels
(Project, Document, Section, Element) of documentation. See page 42 of
[1] for a nice tabular overview of his "documentation is fractal"
philosophy. [2] is his video presentation, and [3] the webpages.

IMO worth at least glancing at for ideas of "What" your documentation
set should contain. I also like his use of Sphinx [4] (and therefore
ReST [5]) but that's a separate issue :)

[1] http://www.slideshare.net/jacobian/writing-great-documentation-codeconf-2011

[2] http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-writing-great-documentation-4899042

[3] http://jacobian.org/writing/great-documentation/

[4] http://sphinx.pocoo.org/

[5] http://docutils.sourceforge.net/rst.html