Brainstorm Thread: http://maemo.org/community/brainstor...documentation/

Summary: Creation and maintenance of help documentation for Maemo 5 devices, based on a wiki format, which is appended to downloadable applications via a system-level API, and stays in sync on the device in a similar fashion to the application via Application Manager Updates.

Long Version: Here's the issue, documentation. No one likes to do it, and to create documentation on the device, is a secondary-side of pain for many developers. Therefore I recommend the creation of a a unified documentation point - the Maemo.org wiki - to which all of those who have Maemo 5/6 applications would append their program's help documentation within this wiki. And through the use of a system-level API (or additional dependency), the developer would be able to include this documentation onto the device as a part of the on-board Help feature. This would be linked through a Help or About menu in the respective application, and then also accessible from the general Help application on the device.

Benefits: the documentation would be in one place - and updated as often as the application itself (if the developer does right). Users would not have to guess at where to find documentation towards their device, and what they find at Maemo.org would be equal to what is on their device.

Note: This idea is not to mean that the entire wiki would be downloaded onto the device, only those entries which are attached (dependencies) to the application. In this way, a person would have just a snippet of the documentation as they need it.

Downsides: Developers would have to write/maintain documentation in addition to their applications (positions for technical writers should open up here therefore). Documentation that is not up-to-date would reflect negatively on the developer's karma rating, which can seem unfair for a popular application that sees frequent downloading and positive comments.

Hmm, I'd also suggest storing them centrally somewhere (e.g. /home/user/HelpDocuments/. But I love the idea.

Volunteering to help anyone who wants with actually writing their 'help' file, especially those needing to write in English when it's not their first language.

Is the idea that anyone with a wiki account could create or update this documentation? If so, then that might be good for developers who don't like writing documentation.

@pelago: yes, anyone with a wiki account should be able to update the documentation. However, when the documentation is applied to an application, there should be some approval process for updates to that documentation (contributor > developer > published) so that items aren't updated mistakenly.

The other part within this is that it should make for another in-road for people to contribute to Maemo projects in a more direct manner. This would essentially be an open invitation from the developer to the community at large. Though I would caution that this could easily be something that a small org/company takes up as their approach to selling support services to open source developers. So caution would need to be applied here.

Excellent idea

EDIT:

Same as Kathy, willing to write help files and help anyone else who needs it. Think this is a really good idea and will help a lot of people out, especially the influx of new users.

What if the developer doesn't want to use the wiki format?

Maybe someone take it upon themselves to write one without the developer, and maybe add disclaimer to the document before it gets published:

"This guide is writen by user only with no developer QC, all infomation should be treated as such........

Ah, there's the winning question. Thanks for asking.

Developers should not be under any obligation to provide *any* documentation towards their materials. This idea - as presented - provides a means for any developer to attain some level of documentation, in a common area, attached to their application, and in a common enough format that they can have a side of their testing/project team dedicated to keeping that updated.

For those developers who'd love documentation help until their UIs become totally intuitive, this is a win for them.

That being said, if they want to provide it in any other fashion, the key point of keeping it updated and available on the device remains. Without up-to-date documentation, then providing it is worthless to the user - and possibly to the developer as well if they choose at some point to no longer handle maintenance of that application/service.

Just had this revelation - I'm working on SharePoint documentation - documentation makes more sense when people get familiar with the product. If they are trying to look at the documentation as some literary set of data, then it won't make sense. The documentation has to invite people to not just use the device, but use it effectively. In that respect, I think this idea while great, needs buy-in from developers to really take off. Else, it will end up being just another book of stuff that's rarely useful.