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.

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?

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

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.

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.

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.

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.

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.

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

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?