RH2015 How to share topics with links

[Guest]

My work has upgraded our version of RoboHelp from 10 to 2015. Previously, we were using a workaround script to manage our single sourcing - however, because of layoffs, I don't actually know how this script works. Basically, it allows the "single-sourced" topic to appear in the webhelp of the project that's referencing the original, but not in the print documentation. So, we updated to RoboHelp 2015, so we could single source properly.

But, here's the issue. I started converting my first project, and pulled in all of the topics that I needed to reference. That all worked fine, except my broken links folder had about 20 broken links. I found that this was because a lot of the topics I was pulling in had links to other topics in the original projects. So, it seems those topics also needed to be pulled in. When all was said and done, I'd almost doubled the number of topics in that project. (Half now being shared from the resource manager.) Some topics even linked to topics that linked to other topics.

Are we doing this correctly? I started with a simple guide as a test and an example, but we have some projects that reference a lot more than this one did. Theoretically, if a topic links to a topic that links to a topic (and possibly ongoing to the nth time), then it seems like these projects could just keep getting bigger. Is there a better way to be doing this? Is there something that we're missing? It seems like there must be ...

Has anyone else worked with this? Any advice would be appreciated!!

Thanks!

[Willam_van_Weelden]

The resource manager is meant to make sharing resources between projects possible. So that is a good way to go.

I do have a question though: Why are you creating separate projects instead of using CBT to conditionalise content and truly single source? Wouldn't that be a better solution? - And you can also conditionalise the hyperlinks in the shared topics and exclude them in your other projects.

[Guest]

Well, no argument that creating a single project and using CBT would be ideal. But we're working with about 25 years of legacy docs. There used to be a dozen writers managing our approximately 60 projects, but there's just the two of us now.

I had considered at one point taking everything that we have and putting it into one or a few larger projects. The problem is that we have 60 projects because we have 30 unique products, and a guide (separate projects) each for system admins and for users. The projects range from as little as 100 topics up to about 1000 at the most. So, I also considered pulling each SA and user guide into a single project so we'd just be working with about 30. Problem with that is that SAs and users go through completely different workflows in completely different UIs. The content that's shared between any given SA and user set is actually surprisingly little. It's more that user guides share content between them and SA guides share content from a bunch of different places. When I realized that, I considered making an SA project and a user project. User guides never refer to SA guides, though the SA guides refer to the user guides quite a bit. That would probably be the most effective way to merge the projects and have it be workable, but the initial time investment to make all of those legacy docs work together wasn't something I could get approved. Having that many writers working over that long means there's some problems with consistency like video folders named in a dozen different ways for example, plus a bunch of images from different projects somehow got the same names, and some other issues that weren't issues until I started looking at this.

I considered conditionalizing the hyperlinks! But wouldn't that just lead to a broken links problem? If I have a topic in project A that I want to share, and I put a conditionalized hyperlink in that topic, and share it with project B, wouldn't the link that's supposed to output in project A still be broken in project B? Even though there's a condition that means it won't appear in the output, the broken links folder is still going to show that topic because that topic is still technically supposed to be able to connect to both of the links, isn't it? And so then it'll be hard to tell which broken links are the result of conditional tagging and which broken links are actually broken.

Which brings me back to the resource manager ... it's possible that because of the way our docs were set up and grew (I don't think there was an architecture plan - I think every doc was developed from a need) that this may just not be something effective for us. In my simple project example in my OP, I ended up pulling in about the same number of topics as what was originally in the guide, just to get to a point without broken links. Project B (the project I was working with) would pull a topic from Project A that linked to Project C, D, and another topic in Project A. Pull all of those in, and then I'm pulling in more topics from C, D, F, and Q to deal with new broken links. And it kept going like that. So I'm not actually pulling in even half of the content from any other single project, yet I'm doubling the content in the project that I'm working in. There's no way that if that's how it works that my coworker (or my manager for that matter) will go for it ... in order to get that sample project to work, it took me about six hours pulling things in, finding and dealing with broken links or unfound baggage files, and actually getting the whole thing to work. I'm sure it'll be faster as I go and get used to it, but that was also a simple project. If I bring this to the people with the power-of-approval, they won't go for it. They'll want us to stick with the original work-around because it works. (Just not ideally.)

It's kind of unfortunate that there's no way to have the links be relative in the shared topic. All of the guides are now stored in the same network location, so I was hoping there would be some way to have the shared topic find the links relatively.

[Amebr]

For the link problem, perhaps you could convert your links to variables. That way you could have "one" link, but each project would output the correct destination for itself.

So you'd have a default set which would contain the standard link destination. Then you'd have a variable set for each user guide or admin guide which would contain the correct destinations as required for each guide.

I don't know how this would affect the Broken Links folder, nor how it would interact with your current workaround, but it might be something to look into for one of the issues you have.

(It also isn't a quick solution, but perhaps it will be possible to run concurrently with your current workaround until you get it all set up.)

[Guest]

The variables idea was pretty great, so I tried it out. (Thanks so much for the suggestion!!)

So, it *does* make the link in the shared topic work in both places. Actually, it works pretty cleanly. If you add the variable in both projects and point it to respective places, the links will work. And you're right, they output the correct destination for themselves. It also doesn't impact the current workarounds because it only affects the topic that I'm specifically working with, which is great!

However, I'm still getting the internal topic that the original link was pointing to, showing up in the second project as a broken link. Which is weird, because the variable in the second project and the link in the second project both clearly show that they're pointing to an external website (I used Google). If I double click the variable in the topic of the second project, it shows me the external link. So, I tried sharing a topic that had a variable defined in the original project but not in the second project, to see if it would try to automatically bring over the variable, and it doesn't. It just shows "ERROR: Variable (Google) is undefined" in the topic.  (That might be documented somewhere, but I tried it regardless.) That would make sense to me if the variables weren't linked at all - as in, if I wasn't getting a broken link with the one that I defined two separate variables for. But it doesn't work quite the way I expected.

It's starting to look like regardless, if something internal is referred to in the original content, it *must* be present in the second project, otherwise it'll be broken. So I guess the process is to share all content that's being referred to? Do other people have this issue? Or is this because we're working with legacy docs that are all separate projects?

[Amebr]

Hmm, I can't offer too much help on those issues. I set up a quick test with multiple variable sets with one containing a non-existent relative link. No broken link displayed for me, even though when I created the link in a topic the normal way a broken link appeared.

To avoid the error, rather than not defining the variable, you could put the following code in the html: <span style="display: none;">a</span>. Possibly the error is there so you don't get the following:

UG1: See "Creating a widget" in <variable txt for UG1>.

UG2: See "Creating a widget" in . <--oops, this is hard to spot.

Although I'm personally not sure whether a missing "word" or an error you only see in the output is worse.