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?
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:
I hope that helps! Let me know if you have any more questions. :)
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.
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.
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.
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:
Unfortunately Confluence does not support this de facto standard.
Do you use templates with Confluence? Take part in a remote 1-hr workshop. You'll receive USD $100 for your time! We're looking for people to participate in a remote 1-hr workshop...
Connect with like-minded Atlassian users at free events near you!Find a group
Connect with like-minded Atlassian users at free events near you!
Unfortunately there are no AUG chapters near you at the moment.Start an AUG
You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs