Skip to main content
B
Brett4
Participant
July 29, 2011
Question

Best Practices for Connecting to WebHelp via an application?

  • July 29, 2011
  • 1 reply
  • 813 views

Greetings,

My first post on these forums, so I appologize if this has already been covered (I've done some limited searching w/o success).  I'm developing a .Net application which is accessing my orginazation's RoboHelp-generated webhelp.  My organization's RoboHelp documentation team is still new with the software and so it's been up to me to chart the course for establishing the workflow for connecting to the help from the application.  I've read up on Peter Grange's 'calling webhelp' section off his blog, but I'm still a bit unclear about what might be the best practices approach for connecting to webhelp.

To date, my org. has been delayed in letting me know their TopicIDs or MapIDs for their various documented topics.  However, I have been able to acquire the relative paths to those topics (I achieved this by manually browsing their online help and extracting out the paths).  And I've been able to use the strategy of creating the link via constructing a URL (following the strategy of using the following syntax: "<root URL>?#<relative URI path>" alternating with "<root URL>??#<relative URI path>").  It strikes me, however, that this approach is somewhat of a hack - since RoboHelp provides other approaches to linking to their documentation via TopicID and MapID.

What is the recommended/best-practices approach here?  Are they all equally valid or are there pitfalls I'm missing.  I'm inclined to use the URI methodology that I've established above since it works for my needs so far, but I'm worried that I'm not seeing the forest for the trees...

Regards,

Brett

contractor to the USGS

Lakewood, CO

PS: we're using RoboHelp 9.0

This topic has been closed for replies.

1 reply

Peter Grainge
Community Expert
Peter GraingeCommunity Expert
Community Expert
July 30, 2011

Brett

Most folks here are authors, as I am, and that is a question best asked of developers.

Yes you can call alternating the call character a hack but one of our senior developers came up with it using his experience. Maybe it is a valid method used in coding and maybe it was a "guess" but it works.

I suspect if you asked a group of developers, you would always end up with two camps who would argue like US politicians over the debt ceiling.

The reason we like URLs is that they are human readable. Also we have a convention for naming our files and the developers know how our files will be named before we create the topics. We don't have to wait on each other.

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

Use the menu (bottom right) to mark the Best Answer or Highlight particularly useful replies. Found the answer elsewhere? Share it here.
B
Brett4Author
Participant
August 1, 2011

I've been giving this some thought over the weekend and this is the best answer I've come up with from a developer's perspective:

(1) Connecting via URL is convenient if (#1) you have an established naming convention that works for everyone (as Peter mentioned in his reply above)

(2) Connecting via URL has the disadvantage that changes to the file names and/or folder structure by the author will break connectivity

(3) Connecting via TopicID/MapID has the advantage that if there is no naming convention or if it's fluid or under construction, the author can maintain that ID after making changes to his/her file or folder structure and still maintain the application connectivity.  Another approach to solving this problem if you're working with URLs would be to set up a web service that would match file addresses to some identifier utilized by the developer (basically a TopicID/MapID coming from the other direction).

(4) Connecting via TopicID has an aesthetic appeal in the code since it's easy to provide a more english-readable identifier.  As a .Net developer, I find it easy and convenient to construct an enum that matches my TopicIDs and to utilize that enum to construct my identifier when it comes time to make the documentation call.

(5) Connecting via URL is more convenient for the author, since he/she doesn't have to worry about maintaining IDs

(6) Connecting via TopicIDs/MapIDs forces the author to maintain those IDs and allows the documentation to be more easily used into the future by other applications worked by developers who might have their own preference in one direction or another as to how they make their connection.

Hope that helps for posterity.  I'd be interested if anyone else had thoughts to add.

-Brett

Peter Grainge
Community Expert
Peter GraingeCommunity Expert
Community Expert
August 1, 2011

Pretty much agreed except

  • Your observation that it is more convenient for the author as they don't have to maintain the IDs. It's also convenient for the developer as they don't need anything from the author.
  • That IDs allow other developers to work their way. What if their way is URLs? I'm not seeing how going for any method is better for the future.

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

Use the menu (bottom right) to mark the Best Answer or Highlight particularly useful replies. Found the answer elsewhere? Share it here.
Terms & ConditionsAccessibility statement
Using the community Terms of use Privacy Cookie preferences Do not sell or share my personal information ad choicesAdChoices