Is AIR the right output to use?

[Jared Hess]

Hello there.

So, let me preface this by saying I don't know a lot about using AIR to view help content nor the limitations an AIR output has. I've built a test file once and played around with it some back in RH 7.

Until now our company has used HtmlHelp (CHM) as our output format, but we're starting a new product, and we need it to have a modern look and feel as well as have the ability to store, display and moderate user comments on topics. Initially, I'm thinking the RoboHelp AIR output might be a good match.

What we need:

• The help must be context sentive.
  
• The help must be dockable inside the UI.
• The help must allow user commenting (similar to that shown in the AIR examples).
• The help must reside locally but have the ability to grab user comments for any who have access to the internet.

One possible problem is our product will have its user interface done using WPF. My first concern is can a WPF user interface support F1 context sensitivty in an AIR  output? Some posts say perhaps it cannot (such as  http://forums.adobe.com/message/2145088).

Also, can you dock an AIR output inside a UI?

If AIR isn't the right output, what would you recommend for the above requirements?

Hope all this makes sense. This is all new to me.

Many thanks!

(RoboHelp 9, Windows 7 64-bit)

[Jeff_Coatsworth]

Locally installed AIR Help can be called from apps - you may experience some difficulty doing it in C# - check the available methods of calling AIR Help in your C:\Program Files\Adobe\Adobe RoboHelp 9\CSH API\ folder.

I don't think it can be docked as AIR Help is a separate installable platform.

Yes it can do commenting & obtain shared comments from an internet location.

[Peter Grainge]

I'm not so sure about the comments being on the internet. To share comments all users have to have read / write access to where the shared comments are stored. It is unlikely that will be the case with an internet location.

Intranet is fine but not the same thing.

I know that RoboHelp Server can be used to store AIR Help comments but unless you already have it, that is a big expense for this one purpose. Even then I am not sure it offers what you want. That will need to be checked with Adobe.

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[johndaigle]

Hi. I'm not a developer and as Peter mentioned, I'm not sure all your requirements may be met. But let me add some info to the mix. This link to the online help offers some documentation for developers on how to use the AIR API for a number of languages.

http://help.adobe.com/en_US/RoboHelp/8.0/RoboHTML/WS5b3ccc516d4fbf351e63e3d11aff59c571-7f43.html#WSD...

Scroll down to find this Subhead: Call a context-sensitive Help function for AIR Help

You might also do a forum search for "RoboHelp Praful Jain" . He is the Adobe engineer most familiar with the APIs and there are a number of his posts which address AIR issues.

Also, should you proceed down this path, you would certainly want to upgrade to RoboHelp 9. Go ahead and download a trial of RoboHelp 9 to get the latest API since RoboHelp 7 only had a "Packager" available at that time. When you install the trial, you will find the AIR APIs here:

C:\Program Files (x86)\Adobe\Adobe RoboHelp 9\CSH API\ActionScript (or whatever language your developer is using)

Finally, the RoboHelp 9 trial also includes a Sample file called Salesbuilder. File > Open > click the Samples folder on the left pane to find. If you open the Salesbuilder sample you will see an explanation of how CSH AIR Help can be implemented. This example shows AIR Help used for an AIR Application, but it could also be a C# application as I understand it.

So, this may not be all you need, but it may show you a way to get there

John Daigle
Adobe Certified RoboHelp and Captivate Instructor
Evergreen, Colorado
www.showmethedemo.com

[Jared Hess]

Thanks for the answers guys.

I don't see C# as a supported language here, so maybe that won't work for us then:

C:\Program Files (x86)\Adobe\Adobe RoboHelp 9\CSH API

We do already have RH 9.

We do not have the RH 9 Server. Is this needed for the user comments from the internet? From this help topic, it sounds like you might be able to do it some other way.

• From the Rh 9 help:

  Set Location For Comments And Topic Ratings Depending on whether you want a trust-based system or user authentication, select one of the following options: Select  Network Folder. Click Browse to choose the shared network folder where  the comments will be stored. Click Add to add locations on Mac and Linux  systems if required. See URL formats for Windows, Mac, and Linux. Specify the password that moderators need to provide to access the moderation dashboard. Select  Pending or Accepted to specify how you want to handle unmoderated  comments. If you select Pending, unmoderated comments are not displayed  to users. Storing  comments in a shared network folder is suitable in trust-based work  environments, where shared reviews by internal stakeholders are part of  the content development process. Select RoboHelp Server and specify the server URL. Storing comments on RoboHelp Server enables you to authenticate users before allowing them to view or post comments. Configuration File Path Specify  the path and name of the file that stores the configuration for comment  syncing and auto-update. When the AIR application is distributed, users  can copy the default configuration file from the !SSL folder of the  project to the location specified in the configuration file path and  modify the default settings according to their preferences. For example,  they can disable commenting or change the location of storing comments. You can enter the path in any of the following formats: A relative path (relative to the install folder) An absolute location, such as a shared network drive or a file location in the user drive A web URL pointing to the location where you’ve posted the XML file

Thanks for the help.

[Peter Grainge]

Where are you seeing that comments can be sent to a URL? The configuration file is something different.

I have checked with Adobe and if you want the comments to be stored on an internet location, you will need RoboHelp Server. That is not a requirement for LAN locations.

There is quite a lot of AIR Help information on my site.

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[Jeff_Coatsworth]

Jared's help reference is on this page: http://help.adobe.com/en_US/robohelp/robohtml/WS81F63111-6ACF-4a02-B2B2-461FEBFA8093.html

Yes, it says you need RH Server if you want commenting to be stored on a web server - "Select RoboHelp Server and specify the server URL. Storing comments on RoboHelp Server enables you to authenticate users before allowing them to view or post comments."

[Peter Grainge]

Jeff

Thanks for the link. That states you need RoboHelp Server but Jared seemed to think it implied other internet options were available and that is the bit I was questioning. I couldn't see where he was drawing that conclusion.

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[Jared Hess]

Thanks for the quick responses.

Peter, I was getting that, incorrectly I suppose, from the above documentation I pasted. Where it gives two options. One using RH Server and one without.

The first bullet item in the documentation I pasted states:

"Select  Network Folder. Click Browse to choose the shared network folder where  the comments will be stored."

But after reading that first bullet item more closely, it sounds like this is something internal to one's company where people on the same network. I guess that's

what's meant by a "trust-based work environment".

"Storing   comments in a shared network folder is suitable in trust-based work   environments, where shared reviews by internal stakeholders are part of   the content development process."

--

So that answers the user commenting piece; that we'd have to get a copy of RoboServer to address that bit. As I stated before, I do have RH Server X5. My suspicion is that we'd need to get RH 9 server, correct?

Regarding context mapping, I'm still not entirely sure if we'll be able to do context mapping to topics given our current user interface development environment (WPF). The link above, provided by John says, "Note: The AIR Help API is provided for many languages including JAVA, VC.NET, CS.NET, VB, VB.NET. The following example shows how to invoke the AIR Help API using Visual C++". The word "including" makes me think it's not limited to just this list of languages, but I'm not sure.

Regarding the docking requirement where the AIR help docks inside the UI, it sounds like that might not be an option either.

[Peter Grainge]

The ability to add comments to RH Server was added to RH Server 9 so that's what you will need.

On CSH, sorry I don't know but I will ask.

On docking, I think that was already answered in the thread.

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[Peter Grainge]

There is some information in my AIR pages about CSH. It might be a better solution for your developers to look at them to work out what they can do.

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[Jared Hess]

Thanks for the help Peter. I've pointed our devs to this forum and will also include your site. We'll look into it further.

However, I'm wondering, if AIR won't give us what we need as far as CSH and docking, are there other outputs that would? Browser-based help or something? That would still let us get user comments (assuming we get the RH Server 9)?

[Jeff_Coatsworth]

Browser-based AIR Help = no commenting

WebHelp Pro = WebHelp flavour hosted on RH Server, can't remember if it does commenting (reg. WebHelp doesn't)

[Jared Hess]

Thanks Jeff. I remember we used WebHelp Pro once back in Rh X5 days on an internal server. Would this type of system allow user commenting from within a local system? We need to have the help files locally on each machine, but would like users to be able to sync and download and grab/post user comments (like they can with a local AIR help).

Also, could it be docked inside the UI of the product? It seems like it could since the help just runs within a browser, right?

[Jeff_Coatsworth]

Nope - see this thread - http://forums.adobe.com/message/3906552 John's post #13 states that neither of the Pro flavours (used on RH Server) do commenting.

[Jared Hess]

I see. So it sounds like if we want to have end-user comments shared with other users in our help output, we would need to use local AIR help tied to RH Server to do this. Although it does sound like Adobe is aware of our desires to have other outputs, beyond AIR help, support the ability for users to share comments on topics, and that may be something supported in future version.

For example, we'd love to have something like the php online help (for example: http://www.php.net/manual/en/function.mail.php)

where helpful user comments and examples, once moderated and approved, follow the help topic. Except in our case, we'd like the help to be on each machine locally and then they have the option of downloading these users comments when they're connected to the internet. Documentation would then, over time, become self-correcting/self-improving as user suggestions, examples, etc are incorporated into future versions of the documentation. That capability tied with the analysis and reporting tools that RH Server provides would, I think, be very useful to any Help author.

[Jared Hess]

Just a followup here and one more question:

• The help must be context sentive. - We got this working by following helpful links on Peter Grainge's site.
• The help must be dockable inside the UI. - We have an alternate solution. We'll dock the HTM directly inside the app in a separate dockable pane. The user can then launch the help and that will call the full Air help.
• The help must allow user commenting (similar to that shown in the AIR examples). - Needs RH Server 9 for end-user commenting to work.
• The help must reside locally but have the ability to grab user comments for any who have access to the internet. - Local Air Help does this.

So my one question is with RH Server and user comments. I noticed when working with the AIR help single source layout that it has these two options for commenting:

If I understand it, option 2 is the only way to get user comments to work. We'd need a copy of RoboServer 9.

My concern is comment moderation. I only see it in option 1. Does RoboServer provide some alternate way of moderating comments?

[Peter Grainge]

JaredHess wrote:

• The help must allow user commenting (similar to that shown in the AIR examples). - Needs RH Server 9 for end-user commenting to work.
• The help must reside locally but have the ability to grab user comments for any who have access to the internet. - Local Air Help does this.

Let's first correct those two points before others misread things.

RoboHelp Server 9 is NOT required to enable commenting. It is only required if the comments need to written to / read from an internet location rather than a LAN. In your case you want the comments to be on an internet location and it is that requirement that makes RoboHelp Server 9 necessary. Comments on a LAN do not require RoboHelp Server.

I believe RoboHelp Server will allow moderation but I need to check that.

BTW. The configuration file path you have shown suggests you think that is related to commenting. It does in fact cover many things. Also it needs to be a path that all the local installations of AIR Help can access. You would also have to explain to users how they change the configuration. Is that something that you would want to do?

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[Jared Hess]

Thanks Peter.

Regarding commenting, I suppose I should have defined end-user better. They are the users of our software. I doubt they will have access to a company's internal LAN (though perhaps there's a way over a VPN to set something like that up), which is why I wrote Needs RH Server 9 for end-user commenting to work.

Thanks for checking up on RH Server's moderation capabilities. Hopefully it does, otherwise I'll have to rethink going with this commenting approach.

Regarding the configuration file, I'm not familiar enough with the AIR help yet to know what the configuration file is for. I assumed it had to do with commenting because it's under this Collaboration tree. In any case since our users will be new to the AIR help, I will be creating some topics describing how to use it. I can discuss the configuration file, if needed, there.

[Peter Grainge]

Using RoboHelp Server, moderators open the AIR help in the normal way and can then click an icon enabling them to log in and moderate comments.

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[Jared Hess]

Awesome. Thanks Peter.

[Guest]

I may have a similar problem, though hesitate to start a new post, so I'll try to be as succinct as possible.

I'm compiling Browser-based Help (with AIR) and when I preview the UI locally, I can see the Comments and Favorites icon on the navigation bar. However, after uploading to an internal Web server where the content resides, the Comments and Favorites icons disappear and are nowhere to be seen. 

Is this because I might be using the Commenting feature incorrectly (e.g. needing RoboHelp Server) as opposed to something else?  I mean, I understand that the feature might not function or work if I'm not using RoboHelp Server, but from a visual point of view, I would think it would still display on the UI, n'est pas?

Cheers,

Michael

Seattle, WA (Disney)

[Jeff_Coatsworth]

No can do - see post #12 in this thread.

[Guest]

So the absolute must-have (in the first instance) is compiling via Adobe Air (with a .air file output). 

And then the need for RoboHelp Server depends on the Internet-vs.LAN requirement?

[Jeff_Coatsworth]

Not sure what you mean - if you need commenting and want to share comments across the internet (as opposed to a local LAN server drive location) you need to create the locally-installed AIRHelp flavour and use RH Server to moderate comments; you don't need RH Server if your locally-installed version is going to use a shared drive for comments on the LAN.