Developer Guide table of contents
 

Hi, we want to discuss the Maemo 6 Developer Guide since the very beginning. So... what about the Table of Contents?

There is a first draft produced by the Documentation workshop at the Maemo Barcelona Long Weekend:

http://wiki.maemo.org/Developer_Guide_table_of_contents

I must say that this first proposal clashes with the structure I had in mind after some thoughts, feedback and discussion specially with Daniel Wilms, one of the guys giving support to those developers not finding answers in the guide.

Maybe the difference relies in the fact that Daniel and I have been thinking more hours about how is the developer life in the times of Harmattan, which is actually (and hopefully) quite different than in Maemo 5 and before:

- Web Runtime comes to the rescue for starters. If you are happy with the features and simplified API it offers then you can forget about all the rest. The installation of the environment should be trivial and the fact that you are writing on top of a Linux environment is secondary.

- The native environment is based on Qt and the Qt tools. It has a Qt style API, meaning that in principle you need to know a lot less about the platform components than currently in Maemo 5 since you are interfacing with Qt most of / all the time. This means that all the description about the Core and Middleware can be put almost in a separate guide for platform developers and the few application developers with very special needs.

- If you are developing in plain Qt there is already great documentation at http://qt.nokia.com/doc/4.6/index.html including tutorials and examples. No need to replicate that, but there will be a need to explain why and when makes sense to use the own Maemo 6 application framework (the dui* libraries on top of Qt.

- There will be application developer SDK AND platform development SDK as separate tools. The current Scratchbox/complicated setting will be promoted for platform development only. Application developers will be directed to specific tools easy to install etc for Web Runtime and Qt native development.

So in practice the broad schema of the ToC could be:

Book 1: Maemo Application Development

- Maemo 6 developer overview

- UI Guidelines

- Web Runtime
-- What can you do
-- HowTo
-- Examples of main use cases
-- Tools

- Native development
-- Qt intro + links to Qt documentation
-- Maemo Application Framework
-- Maemo API (each subsection has intro, examples, link to API docs)
--- Multimedia
--- Connectivity
--- (etc)
-- Tools

- Testing & QA

- Distribution

---------------------------------

Book 2: The Maemo Platform
(less urgent to define)

Re: Developer Guide table of contents
 

qgil, thanks for posting the results up for us.

I'd like to see something along the lines of setting up the development environment and also packaging too. Any chance these could be added or maybe clarify where they would be expected to live in the current structure?

Re: Developer Guide table of contents
 

I would like to see a "Maemo 6 by Example" section somewhere, maybe between "2. SDK" and "3. Getting Src".

Rationale: some learn the basics faster from a development example, that is, an example that explains each step necessary to quickly write your own little fun application. This can be more rewarding than just taking existing example source code and compiling it. it should - by definition - be a skippable section though.

Re: Developer Guide table of contents
 

Yes - this was the result of a whiteboarding session on the ToC.

The reason it was dropped into the page you found it was to support an ad-hoc conference call followup this afternoon whilst I was at work ;)

Nb, at the weekend it was done without reference to any other sources and has a rationale which I presented and was hoping to flesh out a little more with others (inc Daniel).

It's not really a proposal at this point; more a strawman.

Agreed - we did not consider this at the time.

This was mentioned quite a bit in discussion but again, I agree it is not clear at all in the ToC.

The rationale here is that the guides cover the high level APIs first and only then dip down to provide reference information for material where Nokia is authoritative and deltas where Nokia has modified upstream systems.

Yes, the idea of linking out to Qt was emphasised - and Qt was identified as an example of best-of-breed.

OK - so not being aware of this at the weekend we couldn't include it.

OK, will review and comment :)

The idea was to do something 'unconstrained' to see what useful things came out and then to merge that into previously developed ideas so this thread can start that (although a little earlier than anticipated)


One thing that we did provide was a separation between 'setup' and 'coding'.

Setup is the first part and covers the none-code-cutting flow from sdk (or whatever) installation through various resources including mechanics of our compile/build and maemo packaging (acknowledging that windows devs will find this v. new).
Then on to the delivery options (consider how in windows you download Oracle from Oracle.com and yet in our world we get MySQL from fedora.org or debian.org) so we use Ovi and Maemo Extras for this.
I also wanted this to introduce test (and debug?) tools and community QA processes.
Finally to provide additional reading (UI/UX etc) and reference info or links (somewhat embarrassingly we forgot this during the weekend :o )

The 2nd part was loosely based on the platform SW architecture (which we don't have yet so it was hard to use as a basis so I stuck with random examples).

The key messages here were:
* Present the API the dev will hit first, first (eg Qt); then move on to lower levels.
* Document the APIs
* Provide "best practice" guidance (for a concrete example of the mitigated risks here see the FM radio / microphone issue which I *think* would have been avoided although it's an extreme case)
* Provide sample code for everything (nb, unit testing code could possibly be re-used if you thought about it early enough)

OK, last thing we(I) wanted to see was a consolidation application:
When you get within 200m of a friends house a sound or video would play and you'd send them an SMS or start a VOIP call depending on whether you tilted the phone left or right... or something ;)

The point clearly is to have a useless but runnable application that shows *integration* of many of the platform capabilities.

HTH

Re: Developer Guide table of contents
 

Fargus: qgil's post isn't the results of the Documentation Hackfest. This is his own proposal.

I just wish Quim could have provided some of this guidance before the hackfest. This is an expensive way to do it.

Re: Developer Guide table of contents
 

qole, I was waiting for a proposal that I didn't want to influence in any way. The ToC proposed helped me figuring out the aspects and details written few hours ago here. A week ago I wasn't able to make such a proposal.

We are all brainstorming here and my opinion is just that, an opinion. I'm not even a developer myslef.

Re: Developer Guide table of contents
 

Thanks for the clarification guys. The only thing that I havea little concern over is the bit about hierarchical presentation of the API. If you mean segmenting application types as in web api and native then that fine. Within each type of application though the API needs to be based on subsystem divisions inline with framework, if not the documentation will be ignored by the devs I have spoken too and another set painstaking constructed for ourselves as this is the way we expect to find information.

Regarding best practice it might be worth adding some coding standards to cover style and naming if not already considered then following that through with sections from the example programmes to highlight.

Re: Developer Guide table of contents
 

Hi quim,

This is similar to the proposal from Barcelona in respect of having two distinct parts, one for the developer to get started, and another as a reference and guide for the platform;

What I'm missing from your proposed table of contents is getting a development environment up & running. For example, for the web toolkit, what are the prerequisites? What tools do I need? What software do I install? How can I test?

You're still going to need a VM/emulator/Xephyr to test applications, you're still going to need some kind of toolkit to build & package for the tablet and for your test environment (even if you're 100% web & cross-platform, like most Mozilla add-ons, you still need to document how to make an XPI file, test it locally, and distribute it - for a widget for a tablet you need some kind of environment to display & test it).

As you point out, for native/platform applications the set-up gets even more complicated. We still need to help people over the hump of installing everything and building their first application (even if it's only a sample application shipped as source code with the SDK).

Where in your ToC does that fit?

Cheers,
Dave.

Re: Developer Guide table of contents
 

@Fargus
I suggested (and I don't think it was news) that the docs should be strongly supported by a software architecture diagram and that should provide the key navigational hints - and probably provide some flow suggestions too.

Re: Developer Guide table of contents
 

By the way, for those who have not yet gone over to Forum Nokia to see what kind of developer docs they are doing, I just saw (thanks to a pointer from Quim) an amazing "Get started with Maemo in 1 hour" Flash e-learning video (complete with screencasts, etc) at http://www.forum.nokia.com/info/sw.n...h_Maemo_5.html (linked off http://www.forum.nokia.com/Tools_Doc...on/Maemo.xhtml)

Anyone who hasn't had a look recently should head over.

Cheers,
Dave.