Best Practices for Connecting to WebHelp via an application?

[Brett4]

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

[Peter Grainge]

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

[Brett4]

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]

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

[Brett4]

The latter point (my #6) really is a backhand reference to my point #3 and I believe may not have been stated a clearly as I was imagining.  It all goes to code-maintenance and document maintenance.  A naming convention is only as good as the people who agree to it.  And in my experience, these rarely last beyond the original caretakers.  People get lazy or careless and you end up with exceptions to the rule.  If you have a document where for applicaiton #1, the developer had been successfully working with URLs, then the document changed authors and the later author didn't adhere to the convention, a later programmer might be inclined to prefer working with the TopicIDs or MapIDs if those had also been maintained by the original author.  It's all apples and oranges though, really.  People will take the most convenient/easiest path for their specific case.  In my case, my organization seems to like the idea that they can mess around with their folder/file structure and keep connectivity by maintaining the TopicIDs.  They also don't appear to be as comfortable applying a naming convention with the necessary discipline.  As such, even though like you I think it would be an easier road to go with the URLs, we may end up working with TopicIDs in the end.

[Peter Grainge]

Horse for courses, whatever works for the organisation.

As to anyone breaking the convention, we just kill them!

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge