Help support for Adapt It Mobile

[eb1]

We should add help support to Adapt It Mobile; it would be nice if the topics were part of the application bundle, so that the user didn't need to be online when viewing the topics.

Yesterday I came across an example that made use of the Backbone.js router file, so that the routes: selection had a url path for help topics to be swapped into the single page application. Something like this:

routes: {
            "":             "home",     // (top level)
            "help":         "help",    // #help
            "lookup":       "lookupChapter",    // #lookup
            "adapt/:id":    "adaptChapter"     // #adapt/RUT001 (3-letter ID of book + 3 digit chapter number)
        },
        help: function () {
            helpView.delegateEvents();
            slider.slidePage(helpView.$el);
        },

This way, a link to "#help" would route the application to the help function, which would display a helpView within the frame of the index.html page.

[adaptitbruce]

On 13/02/2014 10:51 AM, Erik Brommers wrote:

We should add help support to Adapt It Mobile; it would be nice if the topics were part of the application bundle, so that the user didn't need to be online when viewing the topics.

Yesterday I came across an example that mad use of the Backbone.js router file, so that the routes: selection had a url path for help topics to be swapped into the single page application. Something like this:

routes: { "": "home", // (top level) "help": "help", // #help "lookup": "lookupChapter", // #lookup "adapt/:id": "adaptChapter" // #adapt/RUT001 (3-letter ID of book + 3 digit chapter number) }, help: function () { helpView.delegateEvents(); slider.slidePage(helpView.$el); },

This way, a link to "#help" would route the application to the help function, which would display a helpView within the frame of the index.html page.

— Reply to this email directly or view it on GitHub https://github.com/adapt-it/adapt-it-mobile/issues/23.

Sounds good. I wonder who will redo the helps? Bob Buss is getting on in years, probably in his 70s by now, and I've no idea how hard it is to do helps for a smartphone app. Bob's very good at it - good concise steps and explanations etc.

--Bruce

[eb1]

A basic help link has been added to a few pages, each linking to a main help page. This needs further development however -- I'm pushing this off to the next milestone to revisit this later.

[eb1]

I'm not sure that separate help pages are even necessary. I haven't seen them on apps that I've installed on my phone / tablet -- help is inline when needed.

For milestone 0.30, I've gone through and hidden the help links (they went to a placeholder topic with no real content). We can discuss this and evaluate whether it needs to be implemented.

[adaptitbruce]

I'm not sure either - at least for the kind of helps that the desktop version has. They are good, but maybe AIM users will need fewer? Helps to get going are important, and helps for the main workflow operations involved in adapting are very important. Helps on the KB, and how to set up a kbserver for syncing will be important too. Exports too, I suspect.

--Bruce ----- Original Message ----- From: Erik Brommers To: adapt-it/adapt-it-mobile Cc: adaptitbruce Sent: Wednesday, June 17, 2015 2:17 AM Subject: Re: [adapt-it-mobile] Help support for Adapt It Mobile (#23)

I'm not sure that separate help pages are even necessary. I haven't seen them on apps that I've installed on my phone / tablet -- help is inline when needed.

For milestone 0.30, I've gone through and hidden the help links (they went to a placeholder topic with no real content). We can discuss this and evaluate whether it needs to be implemented.

— Reply to this email directly or view it on GitHub.

[GraeCost]

That's an interesting subject. I find it hard to think of apps for smartphones that have help pages of the sort that are common on desktop apps.

In fact, I think the only smartphone apps I have come across that have any help pages are a few that are on the periphery of "popular" apps. And I have not found their "help" very helpful!

All the usually liked and used apps provide guidance to users by means of their flexible user interfaces. Interfaces that provide just the right kind of guidance at the time and place where it is needed. As soon as a user has to go to a longer document and figure out which bit of it is relevant to his current concern, the developer of a smartphone app has pretty much lost that user (and further sales from that user's friends).

GUI development systems have come a long way towards providing the ability to provide excellent, flexible widgets that are helpful to users in themselves, without needing additional paragraphs of text to educate users.

I suppose I am amongst the majority of users who, on finding an app with a lot to read before I can start to use it, put my time into finding an alternative app, rather than reading pages of documentation!

Because I have never needed to do any real work with Paratext I have not persevered with learning it. But it struck me as an app that needed to have its UI thrown out and completely re-invented. Given the decade or more ago context in which it was developed, and the earlier intention that the only people who would use it were people who had attended a course in using it, its current UI is forgivable.

Years later Adapt It appeared on the scene with some inherent complexity (although not as much as Paratext), but Adapt It did a very commendable job of guiding the user through getting started.

AIM should build on the good lead of AID. I think AIM should avoid providing online help pages except where such documentation is found to be completely necessary. That may well, as Bruce suggests, be about KB maintenance and sharing, and tasks that an administrator in a language project would be expected to do.

All the best,

Graeme

On 17/06/2015, at 10:31 AM, adaptitbruce notifications@github.com wrote:

I'm not sure either - at least for the kind of helps that the desktop version has. They are good, but maybe AIM users will need fewer? Helps to get going are important, and helps for the main workflow operations involved in adapting are very important. Helps on the KB, and how to set up a kbserver for syncing will be important too. Exports too, I suspect.

--Bruce ----- Original Message ----- From: Erik Brommers To: adapt-it/adapt-it-mobile Cc: adaptitbruce Sent: Wednesday, June 17, 2015 2:17 AM Subject: Re: [adapt-it-mobile] Help support for Adapt It Mobile (#23)

I'm not sure that separate help pages are even necessary. I haven't seen them on apps that I've installed on my phone / tablet -- help is inline when needed.

For milestone 0.30, I've gone through and hidden the help links (they went to a placeholder topic with no real content). We can discuss this and evaluate whether it needs to be implemented.

— Reply to this email directly or view it on GitHub. — Reply to this email directly or view it on GitHub.

[adaptitbruce]

Yeah, I think you are right Graeme. If we provide any help at all, I think it should be informative in two ways: a) It tells the user what the feature is that underlies the button press, and b) It tells the user briefly what will happen when the button is pressed. (Not a list of do this, then do that, and then do this other thing, and you'll get this...; but something in a brief sentence that is descriptive of the outcome.) Why? Because buttons have short newspaper-like captions that can't be expected to convey to everyone just what underlies their use. Secondly, if someone is wanting to achieve a certain thing, the information from the help will have some chance of confirming whether or not his expectation of the button matches what is actually going to happen. --Bruce

On 18/06/2015 10:44 PM, Graeme Costin wrote:

That's an interesting subject. I find it hard to think of apps for smartphones that have help pages of the sort that are common on desktop apps.

In fact, I think the only smartphone apps I have come across that have any help pages are a few that are on the periphery of "popular" apps. And I have not found their "help" very helpful!

All the usually liked and used apps provide guidance to users by means of their flexible user interfaces. Interfaces that provide just the right kind of guidance at the time and place where it is needed. As soon as a user has to go to a longer document and figure out which bit of it is relevant to his current concern, the developer of a smartphone app has pretty much lost that user (and further sales from that user's friends).

GUI development systems have come a long way towards providing the ability to provide excellent, flexible widgets that are helpful to users in themselves, without needing additional paragraphs of text to educate users.

I suppose I am amongst the majority of users who, on finding an app with a lot to read before I can start to use it, put my time into finding an alternative app, rather than reading pages of documentation!

Because I have never needed to do any real work with Paratext I have not persevered with learning it. But it struck me as an app that needed to have its UI thrown out and completely re-invented. Given the decade or more ago context in which it was developed, and the earlier intention that the only people who would use it were people who had attended a course in using it, its current UI is forgivable.

Years later Adapt It appeared on the scene with some inherent complexity (although not as much as Paratext), but Adapt It did a very commendable job of guiding the user through getting started.

AIM should build on the good lead of AID. I think AIM should avoid providing online help pages except where such documentation is found to be completely necessary. That may well, as Bruce suggests, be about KB maintenance and sharing, and tasks that an administrator in a language project would be expected to do.

All the best,

Graeme

On 17/06/2015, at 10:31 AM, adaptitbruce notifications@github.com wrote:

I'm not sure either - at least for the kind of helps that the desktop version has. They are good, but maybe AIM users will need fewer? Helps to get going are important, and helps for the main workflow operations involved in adapting are very important. Helps on the KB, and how to set up a kbserver for syncing will be important too. Exports too, I suspect.

--Bruce ----- Original Message ----- From: Erik Brommers To: adapt-it/adapt-it-mobile Cc: adaptitbruce Sent: Wednesday, June 17, 2015 2:17 AM Subject: Re: [adapt-it-mobile] Help support for Adapt It Mobile (#23)

I'm not sure that separate help pages are even necessary. I haven't seen them on apps that I've installed on my phone / tablet -- help is inline when needed.

For milestone 0.30, I've gone through and hidden the help links (they went to a placeholder topic with no real content). We can discuss this and evaluate whether it needs to be implemented.

— Reply to this email directly or view it on GitHub. — Reply to this email directly or view it on GitHub.

— Reply to this email directly or view it on GitHub https://github.com/adapt-it/adapt-it-mobile/issues/23#issuecomment-113143728.

[GraeCost]

Hi Bruce,

On 19/06/2015, at 10:46 AM, adaptitbruce notifications@github.com wrote:

If we provide any help at all, I think it should be informative in two ways: a) It tells the user what the feature is that underlies the button press, and b) It tells the user briefly what will happen when the button is pressed. (Not a list of do this, then do that, and then do this other thing, and you'll get this...; but something in a brief sentence that is descriptive of the outcome.) Why? Because buttons have short newspaper-like captions that can't be expected to convey to everyone just what underlies their use. Secondly, if someone is wanting to achieve a certain thing, the information from the help will have some chance of confirming whether or not his expectation of the button matches what is actually going to happen. --Bruce

Yes, a good policy.

For desktop systems many GUI frameworks provide a way of showing tooltips that do this. I started putting them in my UIPrototype - let the mouse hover over the buttons for going forwards or backwards in the displayed verse items and you will see tooltips like "Go to previous item" when hovering over the button with a left wedge.

But I didn't do any more than that as soon as I remembered I was designing for touch screen devices which don't (yet) have an equivalent of mouse hovering on desktop systems. Although the newest MacBooks have something like that (see below), I am not going to hold my breath waiting for something like that to arrive on the low cost smartphone devices that most KIT users will have.

On touch devices we need to use other ways of providing that extra bit of guidance that desktop tooltips provide.

All the best,

Graeme

The new Force Touch trackpad may look like other trackpads on the surface, but underneath it’s unlike anything that’s existed before. Force sensors detect how much pressure you’re applying, and the new Taptic Engine provides a click sensation when you press anywhere on the surface. Now the click that once was a single, mechanical function is just the start of what you can do with Force Touch. The sensory capabilities of the Force Touch trackpad allow you to tell your MacBook what you want it to do based on subtle differences in the amount of pressure you apply. This makes it possible to perform a variety of different actions in different apps, all on the same surface. And it can respond with haptic feedback you can actually feel, making your MacBook more usable and personal than ever before.

[eb1]

Marking this issue as closed / won't fix. As mentioned in the above comments, mobile apps don't typically have help topics in the same way that desktop applications do. Instead, the user tasks are meant to be simple and understandable, and the help is limited to basic walkthrough helps that orient the user to the UI.

AIM currently has a walkthrough help in the adaptation page; if more are desired, these can be added fairly simply (the framework for adding these help walkthroughs is already in the AIM code). For the 1.0 beta 6 release, I've gone through and removed the hidden help topic code referenced in this issue.