[maemo-community] The role of the docmaster

[From: Jarmo.Tikka at nokia.com]

Hi, 

Some comments below ... :)

>-----Original Message-----
>From: ext Murray Cumming [mailto:murrayc at murrayc.com] 
>Sent: 16 June, 2009 14:03
>To: Tikka Jarmo (Nokia-D/Helsinki)
>Cc: maemo-community at maemo.org
>Subject: RE: The role of the docmaster
>
>On Tue, 2009-06-16 at 11:53 +0200, Jarmo.Tikka at nokia.com wrote:
>> Hi,
>> 
>> >-----Original Message-----
>> >From: ext Murray Cumming [mailto:murrayc at murrayc.com]
>> >Sent: 15 June, 2009 18:06
>> >To: List for community development
>> >Cc: Tikka Jarmo (Nokia-D/Helsinki)
>> >Subject: Re: The role of the docmaster
>> >
>> >On Mon, 2009-05-25 at 16:30 +0200, Murray Cumming wrote:
>> >
>> >Jarmo, maybe you missed this reply. Doesn't this bother you?
>> 
>> I have a lot of issues that bother me and Reference Manual 
>is one of those :).
>> 
>> Reference Manual is not same as API docs as with API docs 
>you can document only how your specific component is used. In 
>Reference Manual we docunment how those specific compoinents 
>are used together in maemo platform. Some other platforms may 
>use those same componetns differently (that is the reason that 
>you CANNOT dcoument usage of your component together with 
>other components in API docs that are componetn specific).
>> 
>> Maemo Reference Manual name if Reference Manual as it 
>references documentation of those specific components chosen 
>to be part of maemo platform and especially how those 
>components work together in maemo environment. We also have a 
>lot of references to documentation of those specific 
>components like their API docs as part of reference manual.
>
>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.

If you make a Google search with "reference manual"
http://www.google.com/search?source=ig&hl=en&rlz=&q=reference+manual&aq=f&oq=

You will get a huge amounth of examples how reference manual looks like.

For me most of them look something similar as Maemo Reference Manual and especially they are much more than just collection of API docs.

>
>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.

Looking for those examples about reference manual most of them seem to be book like documents that explain what certain product is, does and how it is used in "human readable format". Especially those API docs are not in "human readable" format and used only when you need to check something special from some special API.

>
>But I don't think I'm getting anywhere with this, so I'll give up.

I did not get what you actually proposed here. Should we change the name of the Maemo Reference Manual or what? I think we anyhow agree that something like our current reference manual is anyhow needed for maemo?

Cheers,
//Jarmo

>
>--
>murrayc at murrayc.com
>www.murrayc.com
>www.openismus.com
>