Will RoboSource resolve my issues with tracking changes or does someone know a good way to resolve this?

[Lynn_Sterchi]

I have a large RoboHelp project that uses RoboHelp X5 and is compiled as WebHelp, and is not using any means of source control besides manual back ups. Multiple changes are being made to various parts of the project at the same time. These changes are at various stages of development (from prototype, in development, customer is reviewing, ready to go into production). The problem is that once changes are started, the original content/topics that is approved and currently in production is gone. I need to be able to retain those original approved content/topics so that when any part of the changes that are currently being made become approved, I can promote them to production, while promoting the original approved content/topics of the other changes (and not promote the content/topics that is currently in the other stages of development).

I can get around this problem if the changes are only additions to the project and I use various conditional build tags to exclude the new changes until they are approved.

But now that we are doing a lot of revisions to existing content/topics and the conditional build tags don’t retain the original versions of the topics, I don’t have a good way to keep the original versions (retaining the links and keywords) while modifying the topics.

I would like to be able to compile the project at any time to include or exclude various versions of topics. This will allow me to compile a version for my customer to review (that may include topics that are approved and topics that are ready for review). And then I could compile a version for production that would only include topics that are approved (including the original/approved versions of topics that are currently being changed.

It so happens that more than one associate is working on this project at the same time, however, I believe we would still have this issue even if it was just one associate working on the project.

[HKabaker]

Lynn,

For one or two topics, this is manageable.

I would use conditional build tags, as many of our colleagues have done many times..

For simplicity, let's say we have just one topic with two versions.
Call the original topica_v1.htm. Make a duplicate with a filename topica_v2. Revise as necessary.

Assign a conditional build tag V! to the original and V2 to the revision. Create a single source WebHelp layout that excludes topics tagged V1, and another that excludes topics tagged V2.

Put both files into the Table of Contents. Assuming they have the same title (it might be wise to change the title in some subtle way), it will appear in the project as though the TOC has a duplicate entry. However, when you generate WebHelp, the TOC will not list the omitted file. There's some question about how the Index and search will behave; test this.

I try to avoid duplicating topics because it seems to veer away from single-source production.

This could get complicated. If you want to have another version you can copy one (depending on where you want to start) and tag it V3.

Stay with the exclusion approach to the output. In other words,

not V1 and not V3
will allow V2 to go in.

not V2 and not V3
lets V1 get in.

Avoid this kind of Boolean phrase:

V2 and not V1 and not V3.
not V1 and V2 and not V3

Theoretically, either of these should omit V1 and V3, and put out V2 (plus everything else, tagged or not). RoboHelp will let you set it up this way, but apparently can't handle the logic when generating WebHelp or printed documentation. I haven't tried parens ( ) in the Boolean string.

Here's an approach I've used successfully for a three-version output.

Instead of duplicating a topic, and assuming the corresponding topics have something in common, put all of the text into one topic, and tag words and paragraphs as needed. Untagged material comes through for everyone. I've done this with single words, phases, entire paragraphs, graphics, template headers, and tables.

(There's a little wrinkle with tables showing blank rows where text is omitted, but I use a simple workaround to omit those rows.)

The challenge here is managing the conditional parts as you create more and more variations. RH conditional highlighting is useful for tracking the pieces. You can turn conditional highlighting off, which I do from time to time because I can miss small typos behind the colors.

I hope this is useful.

Harvey

[Lynn_Sterchi]

Thanks for your reply Harvey,

Unfortunatly, this is for many more than a couple of topics. And I had also considered duplicating the topics as you have described. But I also had concerns about hyperlinks within those topics and hyperlinks in other topics to these topics. I would need to ensure that the hyperlinks work correctly. It can be done, but may be a lot of work (having duplicate text for hyperlinks pointing to the different versions of the topics and using conditional build tags to distinguish between them).

I was also considering your approach of not duplicating the topics but rather have the topic contain all versions and use conditional build tags to distinguish between the content. I believe it can be done, but again, I think this will be a lot of work and could be very messy, as some of these changes are drastic rewrites.

The other problem is that some associates working on this project don't have the knowledge and experience with conditional build tags, and I can foresee the project getting all messed up.

I don't know much about source control. That's why I was inquiring if that may be an option to help us manage the different versions of content and topics. I just figured this has to be a problem for other organizations too and I wanted to know how you guys handle it. I figure there has to be an easier way that I don't know about or am not thinking of.

Thanks!
Lynn

[HKabaker]

Lynn,

You say it's a large project. Can you say what the numbers are? How many topics are likely to be in flux?

I have another idea that might be practical if , for example, 10 topics are up in the air out of 100. Maybe even 20 out of 100. What's your situation?

How many different versions of the same topic? One original and one revision, or several revisions for a given topic?

Harvey

[MergeThis]

You say: "some associates working on this project don't have the knowledge and experience with conditional build tags," and later you say: "I don't know much about source control." Then you say further: "I can promote them to production, while promoting the original approved content/topics of the other changes (and not promote the content/topics that is currently in the other stages of development)."

Well, those are not your only problems: you and your organization needs to spend some quality time analyzing: 1) just what you actually mean by a 'production' version (that usually means 'ship' version); 2) how many categories you will use; 3) at what stage you can drop off content (say goodbye to it for good).

There's a combination of options you might want to consider: use the topic Status feature along with a series of identifier formats. Any content that is truly in flux can be highlighted (background colors, underline, overline, margin border, etc.). In Topic Properties, select the Status tab and assign one of the RH default status levels (Complete, In Progress, Ready for Review). You can also select items in the To Do List that will be required before the Status can be deemed Complete. You can then run a Topic Properties report to identify the status levels whenever you like.

If your organization continues to push for a more granular tracking level, push back with the notion that this really falls under the responsibility of the IT folks.


Good luck,
Leon


IT: Your IT folks could take images of all source files on a daily/hourly basis for

[Lynn_Sterchi]

Harvey,

There are about 180 topics in this project, and it could be as many of 50 of them that are in flux. It's only because we a going through a major re-write/re-design right now. After this re-write/re-design is complete, then it would be more like 10 topics in flux at a time.

I would love to hear your suggestions!
Lynn

[Lynn_Sterchi]

Leon,

I appreciate your ideas for using the topic status, however that doesn't buy us anything. We can mark the topics whatever status we want, but it doesn't influence what gets included or excluded from the generated help. That's why we use the conditional build tags to mark the status of the text and/or topics.

We do take advantage of marking up the text during development. This helps us during the development process, but it doesn’t influence what gets included or excluded from the generated help. Again, only the conditional build tags can influence the build.

We do have very clear definitions for our conditional build tags. What we mean by ‘production’ version is ‘ship’ version. (In our organization, we don’t ship the online help, we promote it to production. We mainly develop help for internal applications.) Our conditional build tag for this is really “approved” because we have received customer and legal approval.

Our categories (our conditional build tags) have worked well for us, because we have mainly been doing new development. The problem we have now is when updating the content/topics. We may be updating various parts of the online help at any given point, and an urgent request may come in that needs to be updated and promoted immediately. Since some of the topics are in the middle of being updated, the “approved” version is now gone and the topic is now “in progress” which will not be included in the build. Our dilemma is getting that urgent request in production. We don’t have the time to finish our other updates and have them reviewed and approved. So we need to be able to grab the “approved” versions of those topics that are currently being developed. However, as I stated, those “approved” versions are gone (but they do exist in a back-up copy of the online help – but that means they are now in a different project, not the project we are working with).

I’ve thought about creating another instance of the project where I can pull in the approved topics, but I’d have to test that. I’d be concerned about losing the links and keywords. That would be a lot of work to do all of that. So again, I was wondering how everyone else handles this situation.

Thanks!
Lynn

[HKabaker]

Lynn,

I was going to suggest something along the lines of your last paragraph.

Here would be the steps:

1. Duplicate the entire project (you don't need to copy the !SSL! folder, of course.)

2. Open the duplicate -- let's call it the master -- project in RH and delete all of the topics that are not approved. You will see exactly which links are broken.

3. As topics in the working project are approved, import them into the master project. If you have several topic folders, be sure to import the newly approved topics into their proper folders. This will update any links to and from the imported topic. This is important, because the directory path is part of the link.

4. Eventually you will have a master project complete with all approved topics. When the master project is ready, generate output from there.

5. From now on, don't let anyone revise topics in the master project.

Benefits:

--If you use conditional build tags to produce versions with different content, the build setup in the master project is greatly simplified. You can focus on which topics, text and graphics to include or omit, without the complicating factor of revision levels.

--Contributors can revise previously approved topics in the working project. It doesn't matter that you don't have the old approved version there. If someone totally screws up, you can re-import the approved version into the working project.

-- If you have to make last-minute changes, managing the final build will be a lot easier.

OK, it will take some time to get the master project built. But once you do it, burn a CD every time you ship an approved version. You shouldn't need it if you protect the master project. But I can see a situation where you ship a version in June, revise topics and get approval for the December release, ship the December release, find that the new version has been un-approved, and the January release needs to revert to June. It shouldn't happen, but . . .

Someone is bound to point out that this is what version control can do.

But if you're the only person who can generate production output, manual control is easier, I think.

You still could use version control to prevent two writers from revising the same topic at the same time in the working project , and to track checkouts and revisions.

I knew there were reasons I prefer to work independently. This must be one of them.

Harvey