kelley bennett, a Technical Writer at Suncoast Solutions, started out the thread. I've included the comments from other forum members, including mine.
So, just started at a new company. In looking at the current help set up, apparently the person who originally created the online help had no training in HAT use at all. So.. using RoboHelp, she set up a chm for each screen in the application. This means there are hundreds of chms... NOTHING is repurposed... and each time the current writer (besides me) has had to update anything she's had to recompile each chm... and check each one in separately! And i think there might be chm's within chms.. i'm not thoroughly sure how all this is set up, but it's rather daunting... and even, to me, frightening.
I still am a bit clueless as to what's being used to develop various applications here, but there's no way this process is efficient... and it's hideous.. also, they can't really drill down beyond the main screens to get help. Getting help from subscreen at any level requires that you back OUT of everything until you get into the main screen... in order to call the help up.
Additionally, they have rigged it in such a way that the chms are viewed over the network... previoulsy, my understanding was that each CHM would have to be downloaded and viewed locally to be used. However, I found out that they did some sort of scripting or fancy workaround that allowed them to push chms to users for use over the network/internet. At first i couldn't believe it, so I checked Peter Grainge's website and found that there IS a way to beat the system and use a chm over a network. I'm just not convinced that's a good idea.
Additionally, and obviously, this does not allow for any sort of single sourcing.
So, that said, I am writing a proposal for a change in how the help is set up an implemented. I'm thinking it won't require much change for the developers - perhaps revise the current script that is linking all the chm files - but being a very NON-TECHNICAL technical writer, i am not sure what is required for the way things are vs the way things might need to be.
In addition, I'm trying to come up with arguments for the change... the benefits of revamping the help design - which obviously will help the tech writer.
But I have to provide a good enough argument for "The Management"... so here are my questions and anything you can add will be MOST appreciated!
1) what advantages might there be in changing from this bizarre chm mess to a more traditional topic based help?
a) single sourcing is then possible
b) more fluid transitioning within the help presentation to the user
c) more efficient for the technical writer for updating and checking in?
e) someone mentioned to me that using chm over a network/internet could pose a security risk/issue/problem - can anyone verify if this is try or not and why this might be the case?
d) what advantages would updating this help process provide to developers?
e) what advantages would updating this help process provide to users?
f) seems to me (altho, I am not able to verify this at this time) that several smaller chm files would require more space and take more time to load that one larger, traditional, topic-based project would - would you believe this to be true?
g) for thick client app purposes (since recently I've only dealt with web based apps), what would be
the best output for us to propose and why?
OK.. i think that's all i can think of to ask at the moment, but as I said, if you can think of anything else to add for or against my argument to make this change in practice, feel free to list it.
I want to extend my appreciation to anyone and everyone reading and/or responding to this plea for assistance!
THANK YOU!
Comments
Rick StoneAdobe Certified Captivate and RoboHelp instructor
Wow... quite a post there!
1) what advantages might there be in changing from this bizarre chm mess to a more traditional topic based help?
Maintenance is tremendously simplified and by simplifying things, it will result in obvious cost savings.
a) single sourcing is then possible
b) more fluid transitioning within the help presentation to the user
It really depends on how it was set up. For example, if it were set up as a proper merged system, folks would likely not even realize they were dealing with a highly fragmented output.
c) more efficient for the technical writer for updating and checking in?
I'll leave it to someone else to comment on usage of Source Control with this approach. Certainly there is a lot more overhead this way because of all the RoboHelp specific project files.
Inter-topic links may or may not exist today. Certainly it will be very cumbersome to create and maintain these types of links with the existing system.
e) someone mentioned to me that using chm over a network/internet could pose a security risk/issue/problem - can anyone verify if this is try or not and why this might be the case?
Only Microsoft can say for certain, but the reason CHM files no longer easily operate over a LAN is because they discovered a vulnerability.
d) what advantages would updating this help process provide to developers?
For the developers, there would be a single CHM file to deal with as opposed to hundreds.
e) what advantages would updating this help process provide to users?
Without seeing how things are set up, it's difficult to say for certain. But the way it's been described, it would seem that there is no single cohesive way for an end user to easily find information within the complete system.
f) seems to me (altho, I am not able to verify this at this time) that several smaller chm files would require more space and take more time to load that one larger, traditional, topic-based project would - would you believe this to be true?
The CHM acronym means "Compiled Help Module". The process of compiling typically results in space savings. Only by performing a careful analysis would you be able to determine if more space were needed for this method over a single consolidated CHM (or other) methods. But I'd say that generally speaking, that would seem to be the case.
g) for thick client app purposes (since recently I've only dealt with web based apps), what would be the best output for us to propose and why?
Typically folks opt for CHM usage when they have a locally installed software application.
Sounds like you have an interesting journey ahead of you!
Cheers... Rick :)
Carlos Mills
Senior Technical Writer at AWTA Ltd. (Aus)
I have being working with RoboHelp for quite some time and I would recommend to import all Chms into one single project using RH import feature. If you do not have the CHM source files (Word or HTML) you may decompile the CHM files as single projects and then import each of those projects files into your master project.
Even though that involves a lot of work it will save enormously in the long term maintenance and enhancement of the system.
kelley bennett
Technical Writer at Suncoast Solutions
Thanks guys for your input... And yep, Rick, it's quite the mess... Thanks Carlos, for the past 10 years I have not needed to do any importing using RH or Flare so I had completely forgotten that as an option to pull all of the info into one without the old copy and paste tedium... THANKS!
kelley bennett
Technical Writer at Suncoast Solutions
Hi Rick,
Quick question... since I have never used chm for page-level help, I am not sure how that would work. I always thought I would need to use a non-chm form of HTML output... can you provide additional info on using chm for page-level help?
thanks!
Rick Stone
Adobe Certified Captivate and RoboHelp instructor
I've seen it work in a couple of different ways. In way number one, all your "page level" topics are in one single CHM file and all the other typical topics of the system are in a separate CHM file. So in this case you have two CHM files to maintain. One for the CSH page level topics and the other for all the other topics.
The other way is to simply have all topics inside the same single CHM. Then when you need a page level topic for CSH, you call only that topic.
To do this, you use what is called a "Map File". Basically a map file is a text based cross reference. Each potential exit point from the application that would normally open a page level help has a unique identifier. As the help author, you will need to use RoboHelp to establish the correct mapping to topics for each of these identifiers. To get to this area, you open the Project Set-up pod in RoboHelp. In that pod, you should see an area for Context Sensitive Help.
For more details on this process, check out the link below:
http://www.wvanweelden.eu/articles/context-sensitivity-webhelp-and-flashhelp
Note that Willam's article is specific to WebHelp and FlashHelp. But the general principles are the same for CHM.
And here's a Microsoft article on it for CHM (not quite as easy to follow as Willam's article is)
https://support2.microsoft.com/kb/189453
Cheers... Rick :)
Earl Eddings
Advisor: Technical Writer at CSC (GIS)
@Kelley Bennett's original post -- Wow, just wow. That is amazing. *shakes head in disbelief*
Rick Stone
Adobe Certified Captivate and RoboHelp instructor
@Earl - That was my first impression!
Made me recall an old issue from my days working in a call center. I was in a specialized area that supported things that the company I worked for didn't offer. For example, how to install Microsoft Office or how to use Microsoft Paint. Folks paid $2.25 per minute to get advice from me and a co-worker.
Someone called with a problem using the old "Microsoft Cardfile" application. In a similar way to what Kelley was reporting, instead of creating a new card for each contact, they created a complete new Cardfile file for each contact! When it came to light that it was much easier and more efficient to use it as intended, the person DEMANDED that we send Bill Gates to his doorstep so he could fume at him personally.
Ahhh, the good ole days!
Made me recall an old issue from my days working in a call center. I was in a specialized area that supported things that the company I worked for didn't offer. For example, how to install Microsoft Office or how to use Microsoft Paint. Folks paid $2.25 per minute to get advice from me and a co-worker.
Someone called with a problem using the old "Microsoft Cardfile" application. In a similar way to what Kelley was reporting, instead of creating a new card for each contact, they created a complete new Cardfile file for each contact! When it came to light that it was much easier and more efficient to use it as intended, the person DEMANDED that we send Bill Gates to his doorstep so he could fume at him personally.
Ahhh, the good ole days!
A long long time ago, I had a master.cnt file that linked together (roughly) 100 WinHelp files. I had a good reason for doing this - there were 13 collections of screens that went together so there was a 1:1 - and (roughly) 87 .exe files. Anyone that didn't understand the reasoning behind creating 100 WinHelp files would call it a mess.
My point is that there was a reason for doing things the way I did and you don't know the reason the previous writer did things the way they did. Only after you know why can you be qualified to say, "the current setup is stupid and a mess" or "the current setup is not stupid and makes sense." In your shoes, I would dig through any "old" documents or source files for this help system to see if there was any sort of explanation for why it was set up the way it was. Pick the brain of your co-workers that worked with the previous writer and, if it still doesn't make sense, find that writer's email address and ask, "Why did you set up the help files the way you did?" You may be surprised with the response!
Good luck.
Note that each of these had far more information inside them than a single topic. ;)