This content has been marked as final. Show 9 replies
Hi kyleena and welcome to the world of RH forums. There is quite a lot of good stuff on this area in the (cough) RH help. In a nutshell CSH works in one of two ways. Your developers provide you with a list of ids that you map to your help topics. The way I and many other TAs prefer is to create the ids yourself in a map file and then provide these to the developer. Either way, when the user uses the F1 key in the application, a call is made containing the mapid and a map file name which identifies the help topic to open. Exactly how the application call is made depends on the application platform. It is best to speak to your developers in the first instance to get them on board with your way of doing things.
Hi Kyleena and welcome to the forums.
One of the problems with getting started with context sensitive help is that there are many different ways to implement it since it is partially done by the application developer and paritally by the help author. Here are a few questions that might help the people on this forum provide good advice:
Do you currently have a working application or is it just starting to be developed too?
Is the developer someone you work closely with, or someone far away?
What is your time table for producing a working help file after the application is finished?
How large will your project be?
Basically, context sensitive help is implemented by including two files in your help project - a header file (.hh or .h) and an alias file (.ali). The reason for two files is so that the developer can produce one and the help author the other but it doesn't have to work this way. The header file connects the map numbers from the application to an ID and the alias file connects the ID to the topic which you create. You may get the header file from the developer or you may be called upon to create it yourself. These two files are text files so they can be created outside of RoboHelp as well as from within RoboHelp.
it seems that I will be the one to both create the ids and do the other kinds of things. I'm reading lots of articles on the web and now I nearly know how that stuff works, but maybe you can recommend any tutorial/book with samples of how such project must look? I'd be grateful to see some.
Hi Kyleena. I wish I could but as John as already outlined, what you are doing is normally two distinct job functions. I'm not a developer so can't tell you how to code the call from the application. All I can do is tell you what to do from within RH. Try adding a couple of ids to a couple of topics (via the Advanced tab of the Topic Properties). Then look at the project's map file (e.g. projectname.h) which will give you an idea of this side of things. Then you'll have to get someone with developer knowledge to give you the syntax for the application call. Sorry I can't help you with that. There is different syntax depending on the application so I doubt you'll get a book on it. You may be best trying to google.
to answer the questions, the application is ready; the developers of the software are sitting next door; the third question is irrelevant in my case because the application is finished and my deadline is not yet settled. What I have is an Online Help project in RoboHelp that I need to turn into a Context-Sensitive Help. My knowledge of RoboHelp is basic, so I feel like a complete geek. I'm reading the literature on this issue but the stuff I find is purely theoretical without any opportunity for practicing or seeing samples. The tutorial I've read was enough only to get some clue about how it works but not how to implement it to my project.
maybe you can recommend any guide or sample of how the context-sensitive help file should look?
sorry to be a nuisance :)
Thanks Colum :)
I have not yet reached the stage of coding and mapping, the trouble is I still don't get the whole idea of how my target document must look, that's why I don't know how to plan the steps toward the goal and what to search for. I'll follow your advice and try google once more, but maybe you know some groups inside google that are occupied with this stuff?
It sounds like the problem here is that you are not quite sure of how a RH project should be set up to provide CSH and where your role ends and the developers take over. Hopefully I can help you there and then perhaps the fine advice from Colum and John will fall into place.
First there are two issues here. How the project is set up and then how those topics are called.
CSH can be at various levels and that alone can cause confusion. It can mean there is help for every field in the system you are documenting and if the user seeks help, they get information on that field. It would still be CSH if they got help for the screen (form) they are using. So first it has to be decided at what level of CSH is required. That is something for the Product Manager to advise on and the debate should involve the developers and yourself as the decision affects the work involved.
Once that has been decided, then you need to create topics down to screen level or down to field level. Once that has been done, the help content is complete but not necessarily your job.
Next comes the calling of the help from the application and there is no question that is the job of your developers although they will require input from you.
The developers have to decide how they are going to call the help. Is your output webhelp or a compiled CHM file? If you don't know which to use, you need to speak with your developers and find out if the application will be installed on the users PC (you need a compiled CHM file) or on a server (you need webhelp).
With webhelp the developers have the choice of calling the topics using URLs or Map IDs. There's a topic on the former on my site, for the Map ID method my topic points you to John Daigle's topic!
On the CHM method, see John McCallum and Colum McAndrew's posts.
Hope that helps and that I have not stepped on John or Colum's toes.
thank you for the careful analysis of my problem. Your explanation was very close to what's happening, but what is actually happening is I more or less have a clue of how the RoboHelp document must be cooked before, but what I am required to do is to come up with a fine idea of turning the existing RoboHelp project into the CSH. Your explanation contributed to my understanding of the issue, thank you very much. Now I also understand John's and Colum's answers better, therefore it seems to be the time to discuss the issue with my Project Manager in order to get the direction in which I am supposed to move on.
I am likely to be back to this forum, because I am only a beginner in the area of technical documentation and have not yet acquired the needed skills.
Another question I should have asked is what tool was used to develop the application. If it is "completed" perhaps it is already hooked up for context sensitive help. You could ask or you could test this with RoboHelp's BugHunter. With BugHunter enabled, you can press F1 or a help button in the application and if it is ready to go, then BugHunter will return the correct map number for that item. You can then create both the .hh and .ali files to connect the app to the help file.