[maemo-community] The role of the docmaster

[From: Andrew Flegg]

On Tue, Jun 16, 2009 at 12:02, Murray Cumming<murrayc at murrayc.com> wrote:
>
> You are saying that it's a "reference manual" because it references
> stuff, where "references" actually means "contains"? As a native English
> speaker and someone who has spent time among the humans, I don't think
> that makes sense.

Agreed :-)

> A "reference manual" is usually something that _people_ refer to for
> details that they cannot remember precisely. That's why dictionaries and
> grammar rule are in a reference library, but not a novel.

Absolutely. A "reference manual" in (technical) English is a defined
term meaning a definitive API reference, possibly grouped together
into a series of related chapters. Good Javadoc can be a reference
manual, as is the majority of _Java in a Nutshell_[1] and the
"Reference section" in the _BBC Micro User Guide_[2].

A "user/developer's guide" is a structured walk-through of building up
a developer's knowledge to be able to use a system. It introduces
concepts and practices, and builds them up so that the developer ends
up relying on the "reference manual".

The _BBC Micro User Guide_ is a great example of this: the first half
of the book introduces the concepts and how they relate, the second
half is a reference guide to the details of everything you can do with
it.

HTH,

Andrew

[1] http://oreilly.com/catalog/9780596007737/
[2] http://central.kaserver5.org/Kasoft/Typeset/BBC/Contents.html

-- 
Andrew Flegg -- mailto:andrew at bleb.org  |  http://www.bleb.org/
Maemo Community Council chair