[maemo-community] The role of the docmaster

[From: Jarmo.Tikka at nokia.com]

Hi,

If so decided I can go with the Maemo Developer Guide instead of Reference Manual. User Guide goes too close to the end user documentation.

Cheers,
//Jarmo

>-----Original Message-----
>From: aflegg at gmail.com [mailto:aflegg at gmail.com] On Behalf Of 
>ext Andrew Flegg
>Sent: 16 June, 2009 14:12
>To: List for community development
>Cc: Tikka Jarmo (Nokia-D/Helsinki)
>Subject: Re: The role of the docmaster
>
>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
>