Confluence 4.0 context-sensitive online help mapping

[Robert Lauriston]

We're looking at using Confluence to provide context-sensitive online help for our applications.

Normally there's some sort of mapping file or subroutine between the application and the help system so you can change which page is displayed in response to a help call without having to modify the application (as you would have to if you embedded hard-coded URLs in the application). Has anyone set that up in Confluence?

[Robert Lauriston]

The approach Sarah described in her blog post is cruder than the standard header-file approach dating back to WinHelp, which lets you change page names in the help without having to touch anything in the application codeline.

There's a fairly good discussion of that here:

http://docs.madcapsoftware.com/FlareV11/FlareCSHGuide.pdf

Unfortunately Confluence does not support this de facto standard.

[Mick Davidson]

Does anyone know if this information is still relevant?

[SarahA]

Hallo Robert

Yes, we do it that way at Atlassian. We ship a file called "help-paths.properties" with the application. The file contains the base URL of the wiki that hosts the online help, and a set of key-value pairs mapping the screen names (or controls) to the page names. Here's a blog post that explains the process:

http://blogs.atlassian.com/2007/12/using_a_wiki_fo/

I hope that helps! Let me know if you have any more questions. :)

Cheers, Sarah

[Robert Lauriston]

Yeah, I saw that. I'm wondering if we can put the mapping file on the Confluence server so we can change it without having to update the application at the customer's end.

[SarahA]

Hallo again Robert

It seems as if no-one else has any suggestions yet. :) Regarding your question about putting the mapping file on the Confluence server: Yes, that should be fine. The app would then access the file on the server, rather than from the app's own resources.

One advantage of shipping the mapping file is that customers can then update the mappings themselves. Consider this situation: The customers run their application behind a firewall, and do not allow their staff access to the Internet. That makes it impossible for customers to come to your wiki to read the online help. Instead, the customer can download a copy of your documentation, install it on their own server, then update the mappings to point to their own version of the documentation.

Customers may also appreciate this flexibility if they want to write their own procedures based on your documentation, or if they want to install a translated version of the documentation.

You could make the app work both ways. For example, the app could look into its own resources first. If the mapping file is there, use it. Otherwise go and look for the default mapping file on the Confluence server.

Cheers, Sarah

[Robert Lauriston]

Where would I put the mapping file on the server?

Our plan is to remove local help from the application and replace it with a wiki. We have determined that our customers virtually always have access to the Internet from the computers that are running the application, and that PDFs are adequate for the rare occasions that they don't.

[Robert Lauriston]

Where would I put the mapping file on the server?

Do you discuss this in your forthcoming book? http://xmlpress.net/publications/chocolate/

[SarahA]

Hallo Robert,

I don't know the answer to that question. I'm hoping someone else will pop in an give the answer. As far as I can see, the location of the file is not important to Confluence itself. Instead, the application that contains the help links is the one that needs to know the location of the file, and to be able to read the content. The technical writers or other admin people need to be able to update the content.

Cheers, Sarah

[Ritu Sachdeva]

Am also interested in knowing.

Welcome any tips on enabling section level context sensitive help and calling it from an app built on salesforce.com.

[Robert Lauriston]

I don't believe anything has changed as regards Confluence URLs.

Confluence's licensing makes it expensive to use as a help server if you don't want the whole world to have read-only access.