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.

Re: Developer Guide table of contents
 

The ToC I proposed is just schematic. You have "Tools" under Web Runtime and Native development.

Actually no, you don't need Xephyr etc when you have (e.g. and don't quote me) things like Aptana for Maemo or QtCreator for Maemo with a very simple and well documented installation process with all major platform supported (Windows, Mac, Linux). Then installing the environment is not the big issue anymore.

Same can be done with packaging, by the way. You have some source code, you press a button (some magic) and you have a package.

Native and platform development are not equivalent anymore in Harmattan! Again, look at QtCreator and you will see that it has nothing to do with Scratchbox/Xephyr, etc.

I also proposed a separate "Testing & QA" chapter for all the quality considerations to be taken into account beyond the specifics of Web Runtime or Native development.

Re: Developer Guide table of contents
 

Thanks for that - sorry to sound a tad paranoid just some bad experiences with documentation in the past! Sounds as though I ought to have had more faith in the existing team.

Very much looking forward to having somethign to get my teeth into. Are you looking for proof readers for the documentation too?

Re: Developer Guide table of contents
 

Another element to consider is how a wiki page is organized.

For instance, a page like Native/Connectivity/Bluetooth:

- Intro: overview of the features available and the main aspects to consider.

- Link to the full API docs, that should be well documented enough in themselves.

- Few basic examples (few lines of code) for the most usual cases + link to more and more complex examples available in maemo.gitorious.org and even real exemplar OSS projects.

- Tips & Tricks: since this is a wiki real developers could add here their questions, posting the answers themselves or waiting to someone to answer. The input here would help having better API docs, better code examples and better tutorials. Very useful specially in the Alpha/Beta times, when a lot of new questions arise.

- Links to further information e.g. tutorials, generic Qt docs/examples, related platform docs, useful upstream docs...

Re: Developer Guide table of contents
 

Proofreading is one of the main reasons to have the wiki as a master and start having drafts perhaps even before an alpha SDK release.

PS: there is a misspelling in your sentence above. ;)

Re: Developer Guide table of contents
 

First impression, after a very quick look: The one in the wiki is very straight to the matter, you know exactly where you will want to go when setting up your first development environment and start hacking. Quim's ToC is more vague. I would prefer to add the content of Quim's manual (not the ToC) to the wiki proposed doc, under some ToC title, for where specific information can be added about APIs etc.

Re: Developer Guide table of contents
 

Oh yes, about Forum Nokia; I spoke to some representatives there over the w/end including someone (Clemence - marketing company of some sort) doing work for Forum Nokia UK.

It sounds like there will be some followup from them and maybe some focus-group meetings too. I suggested that maybe "Forum Nokia UK" (not Maemo) sponsor a UK-based training/docs weekend session or something.

Just an FYI.

Re: Developer Guide table of contents
 

How do you know which is your "first development environment"?

Are you going to decide that enviroment based on your code skills or on what API / functionality is available to you?

How do you know Maemo is interesting for you in the first place? Installing an SDK means that you have gone already through certain path.

Anyway, this will be a wiki and wiki pages can be moved up & down easily. What about missing content? What about the wiki page contents? What about the "neighbour" documentation?

This is not about Your ToC Against Mine. We are not publishing a printed book.

Re: Developer Guide table of contents
 

Hi,

This is key for me - the developer guide will be a collection of documents that should each be easy to navigate. The idea of "neighbours" to docs is vital - and one of the reasons I hope to see any PDF documents made available as HTML so that we can send people transversally from API documentation of widgets to code samples using them to technical guides of the APIs to UI guidelines and best practices the author should bear in mind when developing.

There are very few developer docs which you read like a novel - the only one I can think of is "getting started" - how to get going as a developer, and what are the basics you need to know. The rest is a network of searchable interconnected material.

Perhaps there has been too much focus on native application development in the wiki. Perhaps the lack of focus on Qt Creator & similar tools is because people aren't using them much yet? We don't know exactly what's going to be available for Maemo 6 so coming up with a table of contents for web APIs and Qt 4.6 is a little tricky.

How about having a "Hello World in 60 minutes" chapter which explains the differences between the various development environments and goes through the hello world process for each (web widget, Qt native app, maybe Hildon native app) as the first chapter?

After that, we can have an overview of Maemo, more in-depth overviews of tools, environments & available APIs on the platform. What's vital is getting someone to the stage where they feel they have accomplished something as quickly as possible.

Dave.

Re: Developer Guide table of contents
 

>This is not about Your ToC Against Mine. We are not publishing a printed book.

No, I understand that. I'm merely looking at the ToC the way I always look at a ToC when I'm starting out with a new SDK and a new API. For that the one published on the wiki is the style I prefer. The version you presented makes me feel I have to read the chapters to see if it is the chapter where I may find what I need - it's not a given, by the section titles.

I prefer the style presented in the wiki ToC, also taken into account that I actually come from using the earlier SDKs. So, what I would like is to simply extend the wiki ToC with more useful stuff, not change what's already there.

Hopefully someone will understand what I'm trying to say, which isn't always the easiest thing! :)

Re: Developer Guide table of contents
 

What if the assumption is that a majority of developers looking to that Guide will be new to Maemo, by default will be interested in the Web Runtime and won't need anything from the rest?

What if about a third will go for the QtCreator path?

What if only a tiny minority will really look at the platform SDK based on Scratchbox, Xephyr etc, and the related documentation?

Re: Developer Guide table of contents
 

That's the problem with fat fingers and an N900! LOL

Re: Developer Guide table of contents
 

Well to be honest I'd be heading straight for the Qt and native development path because of the type of development that I want to do and don't want overhead.

Re: Developer Guide table of contents
 

Looking at the "Lego" part at http://wiki.maemo.org/Developer_Guide_table_of_contents it says "Flow Suggestion - Start with 'upstream' and core linux".

I think this summarizes the approach of the current ToC, and perhaps our collision of opinions. Shouldn't be the other way around? First you have the Maemo API (mostly the Qt frontend) and only if you really are interested in more you go down to kernel etc.

The Developer Guide must put the emphasis on what newcomers need to get started. Any developer with a more advanced knowledge will sooner or later find what he is looking for.

This is why I believe it's worth to start with an intro that even a non-developer could find interesting, continue with easy WebRuntime that even someone that is into web development can give a try, and finally get into native development.

The platform description would be out of scope in the Developer Guide, a separate guide.

I'll draft a ToC in the discussion page since I see my schematic proposal here isn't enough to convince. :)

Re: Developer Guide table of contents
 

Quim, I understand what you mean - don't forget that we covered quite a bit at the weekend - the ToC only represented a small part of the results. I think it would be wrong to take it as anything more than a data point and some general "focus group" opinion.

I am pleased that some of the things we came up with have resonated though - hopefully that'll be useful.

To your particular point: I don't think what ended up summarised in the wiki represents quite what we meant :)

So I think that was just hasty cut'n'pasting from a badly formatted email :)

Better would have been:
2. Flow Suggestion
3. Reference: Start with 'upstream' and core linux

ISTR wanting to have "flow suggestions" as a set of targeted flows for devs from different backgrounds or wanting to do different things (we just had app vs platform but adding web in there makes sense)

Then I think we wanted reference material in 2 parts.

First to see what maemo additions there are to standard linux frameworks (as per examples - and frankly, the less Nokia diverge from upstream, the less content there is here). Much of this would refer out to existing reference docs and would only really discuss local modifications. Essentially Nokia are not authoritative for this.

Then on to the meaty stuff: the maemo specific docs where if Nokia doesn't document it then we don't have a clue ;)

This section was expected to be a reference, not really a book/narrative.

Re: Developer Guide table of contents
 

Just my 2cents, Focus first on getting to core Linux community up and running on developing applications for Maemo and Nokia devices.

This means do a very good job of documenting all low level apis, publish device driver code and clearly highlight highlight how to access the full functionality of the devices.

Basics

* File system details
* Loading operating system
* Battery management
* "Brick" Recovery.... (Assume everyone will brick their system multiple times and make it EASY to recover)
* DBUS

Hardware Specific

* GSM Modem
** Call Control
** Media Control
** SMS Messaging
*** Text
*** Text with Attachments
** SIM manipulation
* Accelerometer
* GPS
* Touch screen
* Wifi
* Bluetooth
* USB
* FM Transmitter

And most importantly, try to consolidate the location of information, provide a real table of contents, and keep the links fresh :) Finding information on Nokia sites can be maddening.

Good Luck....

Re: Developer Guide table of contents
 

VinceC, to be honest I think the primary focus for Maemo 6 are precisely the myriad of developers not necessarely familiar with Linux. Then again most of your points should be addressed by the Qt API.

lbt, I understand the current ToC doesn't reflect the Long Weekend discussions. So what is missing? Let's print now the relevant information before it's forgotten.

By the way, what about some good practices and competitors analysis? What are your preferred developer guides and why do you like them? And viceversa.

Re: Developer Guide table of contents
 

Also, do we all have the same rough understanding about the Nokia Web Runtime? It counts as real application development, not "web development". See the related presentations at http://wiki.maemo.org/Maemo_Summit_2009

Re: Developer Guide table of contents
 

In my opinion Nokia WRT is clearly tailored to web developers, but to produce applications not web sites or web services :).

Re: Developer Guide table of contents
 

Thanks for the reply, my real point is start documenting the low layers first, this is the knowledge only Nokia can provide, the community can provide the high level documentation later or for that matter Nokia can.

This is the same mistake Android is making. Reserving functionality for carriers and close friends until a high level api can be provided to the general development community.

Kind Regards,

Vince

Re: Developer Guide table of contents
 

Hi,

Funny enough, since Maemo is using an entirely free platform (apart from some kernel drivers and small pieces of middleware) the low level APIs are all available already outside maemo.org - Glib & GObject, DBus, the Linux kernel system APIs, libc, Pulseaudio, Upstart, uboot, etc... are all free components, and they're the lowest level APIs you get in Maemo.

The only Nokia-specific APIs are for Hildon (and in the future the Hildon equivalent in Qt), Qt itself in some sense (although there are lots of docs for Qt out there), and all of the hardware-related APIs (telephony, camera, FM radio, accelerometer, ...). Which are quite high level, as APIs go.

Cheers,
Dave.

Re: Developer Guide table of contents
 

I think a simple solution to the issue would be to have a link to other lower level areas of the API in the higher level documentation pointing to the underlying technology associated with the entry. I know this is a lot of work but it would also draw developers into the more advanced topics when they are feeling in need rather than have them create their own solutions in application code.

Re: Developer Guide table of contents
 

A new thead relevant to this discussion: Nokia Web Runtime developer questions