[maemo-community] The role of the docmaster

[From: Murray Cumming]

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:
> >> > > 1. Cleanup existing Chinook documentation for Diablo
> >> > >  - end result for that was Diablo Reference Manual and example
> >> apps in Garge
> >> > >  http://maemo.org/maemo_release_documentation/maemo4.1.x/
> >> > 
> >> > This is a combination of all the existing documentation, right, as
> >> one
> >> > big PDF?
> >> > 
> >> > Or does this contain information or modifications that are not in
> >> the
> >> > regular API reference. For instance, 
> >> > http://maemo.org/api_refs/5.0/beta/hildon/index.html
> >> 
> >> Sorry. I actually looked now. It's a combination of the 
> >> non-api-reference documentation. "Reference Manual" is a bad 
> >name for 
> >> it.
> >
> >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.

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.

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

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