bennypr0fane | # 1 | 2010-11-15, 21:47 | Report

Hello,
I'd like to draw everyone's esteemed attention to the fact that there is no single got-to resource available (or none that I have been able to locate in 8 months of using my N900 in plenty of different ways and scouring through the Maemo universe) for finding USAGE INSTRUCTION AND DOCUMENTATION (documentation as in user relevant information stating what this app can and cannot do). When searching for information that is not directly provided with the app/on the device, such can be found in all kinds of places - or not at all.
So here is what I am suggesting, most naively and bluntly:
All the great people out there who have found it worthwile writing/maintaining an app for Maemo should be obliged, in the process of pushing an app to the community repos, to write a minimum of lines stating rather precisely, in non-tech language (readable by numbnuts like me) its functionalities and, as not all apps and their various functions are completely self-explanatory, leave a minimum of instructions on how to use them. All this compulsory information should always be left in one and the same site, which is made known and public to all beginners who are new to the rather intricate inner workings of this rather fascinating world...

Laughing Man | # 2 | 2010-11-15, 21:53 | Report

You would never see applications published in the community repos in this case. And it isn't that hard for developers to host their applications on other repo's. And you really don't want to get into that headache again (coming from the n800 days). This has been mentioned before, the solution was that people in the community should get involved and post information on the maemo wiki. But nothing ever resulted with that since most people don't want to take the time to write. Which I don't find surprising =P.

ericsson | # 3 | 2010-11-15, 22:00 | Report

Nice idea, but it would't work. It would make everything way too easy, and take too little time. People here likes to search, and put every piece of info spread out in threads with 1000+ posts, if for no other reason than to make the searching experience more enjoyable.

bennypr0fane | # 4 | 2010-11-15, 22:09 | Report

While it is a known fact that almost everybody (including myself) hates doing documentation - especially when you're somehow obliged to do it - I still find it hard to imagine how a few lines of ordinary, but almost-as-useful text would create such an enormous barrier to someone who writes many many lines of computer code every day for a living. No offence at all, really - just trying to understand how this process works...

Saturn | # 5 | 2010-11-16, 00:45 | Report

There is this requirement to be accepted to extras of a bare minimum of understandable description.

Propose directly if you have an example of missing documentation and engage to correct/improve it. The wiki is editable by all and you can contribute. Many times the developers are not the ones you would like to see documentation from.

In the end, you can't oblige people to give you more when their offerings are from their time/pocket.

Laughing Man | # 6 | 2010-11-16, 01:02 | Report

I personally don't find it hard to comment code but I have written technical guides to document how to utilize the software I created or even the machines in a laboratory. I guess part of it is that you don't want to write something that leads to a user misunderstanding. Though that's personally my own reaction and I come from more of a usability standpoint.

Don't get me wrong, I do think it's needed. But encouraging developers to do it is another story. =P

rotoflex | # 7 | 2010-11-16, 01:03 | Report

I'm reluctant to be critical in someone else's house, but documentation is just one aspect of the larger problem.

maemo.org is a swamp, & doesn't even have a site map. Trying to remember what page you saw something on, where a wiki is, why the wiki index for a subject you're looking at now doesn't look like the wiki index for the subject you remember, looking for the development & voting page for an app, having no information to differentiate between garage.maemo.org and a development page, instructions that are constructed to be narrative & not algorithmic, it gets hopeless fast.

My understanding is that the website was a gift from Nokia, but it has become the messy shop that only people who have worked in it from day one can find anything or get anything done.

I have programmed in C for more than a decade (and asm and Clipper before that!), & I gave up on step 9 of wherever the page was on getting started in developing for maemo due to loss of time & patience. I sort of feel like undertaking another expedition to find that page would be too annoying to bother with it at all. The lowest-contrast website layout I've seen on the internet pushing readability down to the bottom does not help much either.

I sincerely hope the Meego community undertaking gets off on a better foot. I wouldn't mind updating the wiki entry for an application's user docs, but finding the page in this swamp & then the prospect of how difficult & unlikely others will find it makes me give it up as near pointless.

mr id | # 8 | 2010-11-16, 01:11 | Report

I'm not attempting to invalidate any of your points, but the link in the main menu DEVELOPMENT http://maemo.org/development/ has clear links to getting started with development - setting up the SDK etc. Not saying they're exhaustive but they are only one click away and should make sense to someone with your programming experience.

Saturn | # 9 | 2010-11-16, 02:39 | Report

I agree the default is awful for me too. Just go to the bottom of the page and change the theme to "classic dark" - your cookie will remember it for you thereafter.

hih