[maemo-developers] Request: Tutorials & use-cases for documentation

[From: Dave Neary]

Hi everyone,

Titta from Lionbridge has been working hard in recent months to
understand what is needed to make Maemo's developer documentation rock,
and one of her key goals is to ensure that the Maemo community is
involved in the creation of documentation - but setting priorities and
helping write and improve documentation.

Her group has just created a "Use-case template" in the wiki:
http://wiki.maemo.org/Documentation/Use_case_template

The idea of a Use-case, as Titta has explained it to me, is that this
will be a very focussed document which will explain how to solve a
particular problem with the Maemo platform. It's not API documentation,
nor is it an overall guide of the platform, it's a stand-alone piece of
documentation that helps a developer perform a frequently requested task.

Some examples that came to mind when we were talking about this were:

* How can I get & use accelerometer data on the N900?
* How can I get a list of media files on the device?
* How can I create a new sharing plug-in for my favourite online service?
* How should I store & retrieve configuration for my application?

Some of these may be API-specific (like the last one & gconf), but the
API is the question, not the answer. The general principle is: make sure
that the question you want answered is a well defined problem that a
developer might have, and doesn't make any assumptions about the
platfoiorm (that's what the answer's for).

So what's next? We want to gather suggestions for use-cases that need
documenting, then we'll create a wiki page for each one, then we (and by
we, I mean "the Maemo Community" will answer the questions. The answers
will include code snippets, and brief introductions to the purpose of
any libraries we use. The end result should be a library of code
snippets that could potentially become a Maemo cookbook.

So - the floor is open! Don't all shout at once. What stuff would you
like to know? Or, having run the gauntlet & solved a problem in the
past, which things do you think should be more clearly documented &
explained? Want to help document your struggles?

Thanks for all your help!

Cheers,
Dave.

-- 
maemo.org docsmaster
Email: dneary at maemo.org
Jabber: bolsh at jabber.org