[Sandbox] Dynamic Help Documentation
 

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.

Re: Feature: Dynamic Help Documentation
 

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

Re: Feature: Dynamic Help Documentation
 

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

Re: Feature: Dynamic Help Documentation
 

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.

Re: Feature: Dynamic Help 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.

Re: Feature: Dynamic Help Documentation
 

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.

Re: Feature: Dynamic Help Documentation
 

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

Re: Feature: Dynamic Help Documentation
 

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

Re: Feature: Dynamic Help Documentation
 

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.

Re: Feature: Dynamic Help Documentation
 

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.

Re: Feature: Dynamic Help Documentation
 

I haven't seen this post. But I have also started a thread and a brainstorm about documentation. The last solution was more or less this proposal...

Please take a look:

http://maemo.org/community/brainstor...ion_framework/


I think that maemo 5 really needs some sort of documentation framework. Maybe a community-driven one can work fine.

Re: Feature: Dynamic Help Documentation
 

Dear all!

As I am one of those "impossible freak" who didn't used linux from born:). But I am interested in this ome years ago. Unfortunatelly I have to work with other o.s. So usually if i have an issue just type man ... then /to search and q. Now I bought this n900 good to learn while traveling... No man pages avaiable at first bullet

I have tried info as well which is bigger and deeper stuff but also have a worse performance... it's missing. when i try to install phone tell me it cannot be installed but sources found... I won't install easy debian again it usually kill my battery. Isn't possibke to make ur knowladge base help files but also build us a manpages package i prefer console better than X.

I think if someone want to fill his rootfs make him able to do with more packages from standard gpl gnu stuffs. I also missing many many useful stuffs for example w3m hey I have mobilinter and limited. if you don't give us man to read then give w3m!!!
:)
thx
Szilveszter

Re: Feature: Dynamic Help Documentation
 

Hi,
We can implement the open source Darwin Information Type Architecture open toolkit (DITA OTK). See http://en.wikipedia.org/wiki/Darwin_...g_Architecture for more information.
This is a JAVA-based, ANT script based tool. It has a standard set of DTDs where you can write all the content (task/concept/reference) in XML format and assemble them into a ditamap/bookmap and create multiple output formats like PDF, HTML help, CHM, JAVA help, and eclipse help. Let me know if we need to get this started.
Thanks,
Ravi