Reply
Thread Tools
ARJWright's Avatar
Posts: 857 | Thanked: 701 times | Joined on Jan 2008 @ Nomadic
#1
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.

Last edited by chemist; 04-28-2010 at 09:01 AM. Reason: status
 

The Following 4 Users Say Thank You to ARJWright For This Useful Post:
Posts: 4,556 | Thanked: 1,612 times | Joined on Dec 2007
#2
Hmm, I'd also suggest storing them centrally somewhere (e.g. /home/user/HelpDocuments/. But I love the idea.
__________________
Originally Posted by ysss View Post
They're maemo and MeeGo...

"Meamo!" sounds like what Zorro would say to catherine zeta jones... after she slaps him for looking at her dirtily...
 
RevdKathy's Avatar
Posts: 2,173 | Thanked: 2,665 times | Joined on Oct 2009 @ Cornwall, UK
#3
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.
__________________
Hi! I'm Kathy and I'm a Maemo Greeter! Welcome.
Useful links for newcomers: New members say hello , New users start here, Community subforum, Beginners' wiki page, Maemo5 101, Frequently Asked Questions (FAQ)
Did you know Meego.com has forums too?
 

The Following User Says Thank You to RevdKathy For This Useful Post:
pelago's Avatar
Posts: 2,112 | Thanked: 1,484 times | Joined on Mar 2008 @ Oxford, UK
#4
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.
 
ARJWright's Avatar
Posts: 857 | Thanked: 701 times | Joined on Jan 2008 @ Nomadic
#5
@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.
 
Posts: 248 | Thanked: 66 times | Joined on Oct 2009 @ Birmingham
#6
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.

Last edited by davedickson; 11-29-2009 at 02:21 PM.
 
Posts: 307 | Thanked: 157 times | Joined on Jul 2009 @ Illinois, USA
#7
What if the developer doesn't want to use the wiki format?
 
Posts: 248 | Thanked: 66 times | Joined on Oct 2009 @ Birmingham
#8
Originally Posted by mmurfin87 View Post
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........
 
ARJWright's Avatar
Posts: 857 | Thanked: 701 times | Joined on Jan 2008 @ Nomadic
#9
Originally Posted by mmurfin87 View Post
What if the developer doesn't want to use the wiki format?
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.
 
ARJWright's Avatar
Posts: 857 | Thanked: 701 times | Joined on Jan 2008 @ Nomadic
#10
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.
 
Reply

Tags
applications, documentation, support, wiki

Thread Tools

 
Forum Jump


All times are GMT -4. The time now is 12:59 AM.