Re: A proper home page in maemo.org with help wiki for each app in Extras

[Dave Neary]

Hi,

Ryan Abel wrote:
> This isn't really any easier than bundling the docs with the application 
> package itself and marginally more complicated for both the developer and the 
> user. If the docs package is in user/*, then it's cluttering up the 
> application manager and you need twice the amount of effort to get it 
> promoted to Extras. If it's not in user/*, then the user has yet another 
> invisible package sucking up space.
> 
> I don't see any reason why we couldn't have a Documentation field on the 
> Downloads page linking wherever.

I see definite potential here - especially if we require a standard docs
template that people can follow & just fill out, the way Bugzilla
provides a bug template.

We'd need to have an easy way to augment wiki pages with things which
are vital in docs like screenshots, though.

Cheers,
Dave.

-- 
maemo.org docsmaster
Email: dne...@maemo.org
Jabber: bo...@jabber.org

___
maemo-developers mailing list
maemo-developers@maemo.org
https://lists.maemo.org/mailman/listinfo/maemo-developers

Re: A proper home page in maemo.org with help wiki for each app in Extras

[Floriano Scioscia]

This is a good idea for optional in-depth software documentation, like in
your case, or power-user "tips and tricks", like the configuration database
that is being collectively built for Dexter text-tv reader on
http://wiki.maemo.org/Dexter .

However, basic help should stay on the device IMHO. As others pointed out,
we cannot assume the user device is always online.

Furthermore, managing localization would be more complicated. One big Wiki
page for all languages would be confusing, and several Wiki pages for
different languages can potentially lead to mis-aligned information,
particularly if users contribute to the Wiki.


> From: "Sascha Mäkelä" 
> To: maemo-developers 
> Date: Fri, 12 Feb 2010 22:05:55 +0200
> Subject: A proper home page in maemo.org with help wiki for each app in
> Extras
> While writing help files for my current project, I came to a conclusion
> that it would be easier to have the app simply point to a wiki page. This
> way a new version of the app would not be needed for changes/corrections in
> the documentation.
>
> Now since we already have a Downloads page in maemo.org for all the apps
> in Extras, why not add a proper wiki for them too. This could be optional,
> of course. But I would see this as a good way of having
> consistent documentation for apps in Extras.
>
> While we are on the subject of a home page for each app, let me bring up
> the donate button again. This would be an easy and consistent place to put
> it. Again, this would be optional.
>
> What do you think? Could this work or am I completely misguided here?
>
>
> Cheers,
>
> Sascha
>
>
___
maemo-developers mailing list
maemo-developers@maemo.org
https://lists.maemo.org/mailman/listinfo/maemo-developers

Re: A proper home page in maemo.org with help wiki for each app in Extras

[Sascha Mäkelä]

On Fri, Feb 12, 2010 at 23:16, Ryan Abel  wrote:


> This isn't really any easier than bundling the docs with the application
> package itself and marginally more complicated for both the developer and
> the user. If the docs package is in user/*, then it's cluttering up the
> application manager and you need twice the amount of effort to get it
> promoted to Extras. If it's not in user/*, then the user has yet another
> invisible package sucking up space.
>
> I don't see any reason why we couldn't have a Documentation field on the
> Downloads page linking wherever.


I agree. Maybe a working solution would be to have a very basic help
included with the app, as Bernd pointed out, and then have the more
comprehensive documentation in maemo.org.
___
maemo-developers mailing list
maemo-developers@maemo.org
https://lists.maemo.org/mailman/listinfo/maemo-developers

Re: A proper home page in maemo.org with help wiki for each app in Extras

[Ryan Abel]

On Feb 12, 2010, at 4:12 PM, Ajai Khattri wrote:

> On Fri, 12 Feb 2010, Sascha Mäkelä wrote:
> 
>> While writing help files for my current project, I came to a conclusion that
>> it would be easier to have the app simply point to a wiki page. This way a
>> new version of the app would not be needed for changes/corrections in the
>> documentation.
> 
> What about providing the help as a separate package? That way, you can 
> distribute help updates any time you like. You could also make it a 
> dependency of your app to ensure it always gets installed alongside your 
> app.

This isn't really any easier than bundling the docs with the application 
package itself and marginally more complicated for both the developer and the 
user. If the docs package is in user/*, then it's cluttering up the application 
manager and you need twice the amount of effort to get it promoted to Extras. 
If it's not in user/*, then the user has yet another invisible package sucking 
up space.

I don't see any reason why we couldn't have a Documentation field on the 
Downloads page linking wherever.
___
maemo-developers mailing list
maemo-developers@maemo.org
https://lists.maemo.org/mailman/listinfo/maemo-developers

Re: A proper home page in maemo.org with help wiki for each app in Extras

[Ajai Khattri]

On Fri, 12 Feb 2010, Sascha Mäkelä wrote:

> While writing help files for my current project, I came to a conclusion that
> it would be easier to have the app simply point to a wiki page. This way a
> new version of the app would not be needed for changes/corrections in the
> documentation.

What about providing the help as a separate package? That way, you can 
distribute help updates any time you like. You could also make it a 
dependency of your app to ensure it always gets installed alongside your 
app.


-- 
Aj.

___
maemo-developers mailing list
maemo-developers@maemo.org
https://lists.maemo.org/mailman/listinfo/maemo-developers

Re: A proper home page in maemo.org with help wiki for each app in Extras

[Bernd Stramm]

On 12/02/10 15:05, Sascha Mäkelä wrote:
While writing help files for my current project, I came to a 
conclusion that it would be easier to have the app simply point to a 
wiki page. This way a new version of the app would not be needed for 
changes/corrections in the documentation.


Now since we already have a Downloads page in maemo.org 
 for all the apps in Extras, why not add a proper 
wiki for them too. This could be optional, of course. But I would see 
this as a good way of having consistent documentation for apps in Extras.


While we are on the subject of a home page for each app, let me bring 
up the donate button again. This would be an easy and consistent place 
to put it. Again, this would be optional.


What do you think? Could this work or am I completely misguided here?


Cheers,

Sascha


___
maemo-developers mailing list
maemo-developers@maemo.org
https://lists.maemo.org/mailman/listinfo/maemo-developers
   

It is good to assume the least when users go to the help facility of an app.
For example, it is good to not assume that you have network connectivity
when the user needs help. I would include at least a minimal help page
that resides on the device. Perhaps even in the app code.

Happy sailing,

Bernd


___
maemo-developers mailing list
maemo-developers@maemo.org
https://lists.maemo.org/mailman/listinfo/maemo-developers

A proper home page in maemo.org with help wiki for each app in Extras

[Sascha Mäkelä]

While writing help files for my current project, I came to a conclusion that
it would be easier to have the app simply point to a wiki page. This way a
new version of the app would not be needed for changes/corrections in the
documentation.

Now since we already have a Downloads page in maemo.org for all the apps in
Extras, why not add a proper wiki for them too. This could be optional, of
course. But I would see this as a good way of having
consistent documentation for apps in Extras.

While we are on the subject of a home page for each app, let me bring up the
donate button again. This would be an easy and consistent place to put it.
Again, this would be optional.

What do you think? Could this work or am I completely misguided here?


Cheers,

Sascha
___
maemo-developers mailing list
maemo-developers@maemo.org
https://lists.maemo.org/mailman/listinfo/maemo-developers