Attempt at Modular with WebHelp

This is the place to discuss Help & Manual 4 issues. Please don't post questions on any other versions here!

Moderators: Alexander Halser, Tim Green

Post Reply
User avatar
cindynotbrady
Posts: 157
Joined: Wed Mar 01, 2006 3:49 pm
Location: Provo, Utah

Attempt at Modular with WebHelp

Unread post by cindynotbrady »

The head programmer of the software I'm writing for does not want to include .chm help in the program. He wants only browser-based help our customers can access from a Web site.

We currently have four writers working simultaneously on this project. My current work around for our modular help is that when the other writers are done writing on their topic, they e-mail me, then I copy and paste the .hmx file they're working on into a master .hmx file, and then I build the help file into a browser-based help project that includes an all-inclusive Table of Contents.

This is problematic if we need make changes to the master help but forget about making changes to the individual help topics.

I'm wondering if there isn't a better solution. If we upgraded to H&M 6, would Snippets help us? Can you include snippets in Web-based help, and do they appear on the Table of Contents?

I know with DreamWeaver we can each edit our own topics, but I want to avoid using DreamWeaver.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Attempt at Modular with WebHelp

Unread post by Tim Green »

Hi Cindy,
My current work around for our modular help is that when the other writers are done writing on their topic, they e-mail me, then I copy and paste the .hmx file they're working on into a master .hmx file, and then I build the help file into a browser-based help project that includes an all-inclusive Table of Contents.
Even with HM4 there is a more efficient way to do this. There is no need to copy and paste. Instead, you can insert multiple projects in the TOC of the main project in the same way that you insert normal topics. Then when you export to webhelp everything is merged into a single webhelp system as though the source were a single project.
This is problematic if we need make changes to the master help but forget about making changes to the individual help topics.
Exactly. Using modules has the great advantage that the individual modules remain separate and can still be edited on their own. So if you need to make changes to your module you can still do that, separately from the main help. Then the project manager just links in your updated version of your module before exporting the final version. See the section of the help on Modular Projects for full instructions on how to use these features.
I'm wondering if there isn't a better solution. If we upgraded to H&M 6, would Snippets help us? Can you include snippets in Web-based help, and do they appear on the Table of Contents?
Snippets are edit-time components, not display-time components. They allow you to create libraries of reusable content blocks and insert them in your projects as live links so that they automatically update in all the projects where they are used when the source snippets are edited. However, this only applies for the source projects. When you export your project to WebHelp (or any other format) the snippets are copied into the topics where they are used and become normal content there. When you export your project, you always get the latest version of the snippet at the time of export, but it doesn't change after that. If the snippet is updated, you need to re-export your project to get the new content. In addition to this, snippets can also be inserted in copy/paste mode, so that they immediately become an editable part of the topic, for example for standard tables that you want to fill with different content every time you use them.

So snippets will provide you with much more flexibility for reusable content, but they are not necessarily what you are looking for for multi-user editing. However, that is supported in HM6 as well. In addition to all the modular project features you already have, it is now possible for multiple authors to work on the same project at the same time. When one user edits a topic that topic remains read-only for the other users until the first user saves their changes.

If you are all in the same office on the same local network you just need to put the project on a server folder where all authors have access and all users can work on the same project at the same time. If you are in geographically separate locations you can still work on the same project at the same time with the help of Help & Manual 6's version control system support. This works like this:
  1. The project is stored in a database in the main office that is managed by the version control system.
  2. Each user creates a local copy of the project on their own computer that is linked to the main database version.
  3. When a user edits a topic on their local copy a message is sent to the database, automatically locking that topic on all the other users' local copies until the first user has saved their work.
  4. When the first user saves their work, the changes are sent to the database version and the topic is unlocked again for the other users.
  5. When another user edits their local copy, it is automatically updated with the latest changes before they start work.
This also works across remote connections, for example via a VPN connection via the Internet. It is safe and reliable, because all users are editing on their local copies and only the changes made are transferred via the Internet connection. At the same time, you have the advantage that you are all always working on the same project, so the problem of synchronizing and merging different versions doesn't arise.

At the moment HM6 only supports Microsoft Visual SourceSafe as the version control system. In the 6.1 update which will be released as a free upgrade for registered users later this year support is also going to be added for Team Foundation Server and SubVersion.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
cindynotbrady
Posts: 157
Joined: Wed Mar 01, 2006 3:49 pm
Location: Provo, Utah

Re: Attempt at Modular with WebHelp

Unread post by cindynotbrady »

Tim, as always, your help was spot on. It worked like a charm! I am so excited about this! Since we all work in the same room and have access to the same networks, I just used your idea for inserting another help file.

Thanks so much!
User avatar
cindynotbrady
Posts: 157
Joined: Wed Mar 01, 2006 3:49 pm
Location: Provo, Utah

Re: Attempt at Modular with WebHelp

Unread post by cindynotbrady »

I have one more question about this. If we're all working on separate files, and then I include each file into a master help, should I make sure that each Topic ID is unique? For example, one writer has a Topic ID named "AccountNumber" in his help project; and another writer also has an "AccountNumber" Topic ID in her help file; should I make sure those are unique? So rename one as "AccountNumberPatientScreen" and another as "AccountNumberPaymentScreen"? Or can they be the same?
User avatar
cindynotbrady
Posts: 157
Joined: Wed Mar 01, 2006 3:49 pm
Location: Provo, Utah

Re: Attempt at Modular with WebHelp

Unread post by cindynotbrady »

I think I answered my own question. I built the master help and made sure to include two of the modular files with the same Topic IDs. The build took the definition for the first Topic ID and applied it to the other one. So in short, I must have different Topic IDs. Good to know before I go much further.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Attempt at Modular with WebHelp

Unread post by Tim Green »

Hi Cindy,

Yes, you need unique topic IDs. Help & Manual can automatically generate per-project prefixes for your IDs so that you don't need to worry about this. See this topic in the help for details on this and other strategies for avoiding duplicate conflicts in modular projects.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Post Reply