Should I merge or use global project linking?

[KJKurth]

I don't have a difficult problem, I'm just trying to figure out whether merging projects is best for my situation or whether I should use global project linking. I've never had to do either before. I just need some info on the pros and cons, so I can make a decision on which way to go.

I'm working on several related products that are installed on a computer. Even though these are standalone products, they do have a number of pages in common. Therefore, I need to update the topics for these pages in the help for each product. Some notes:

• * I'm creating HTML5 help using Flare 8, though at some point I'll also need to be able to use these common topics in Mobile help.
  * These topics are set up in the alias files for each of the projects so the context-sensitive help works.
  * We use source control, so I'll always have access to the project source files.
  * In a few months, we'll be upgrading to Flare 10.

I'm leaning toward using global project linking and setting up a separate project that I'll use just for importing those common topics into the various other projects. Are there any gotchas I should know about? What about my context-sensitivity? If I create the header file and alias file in the common project, can I import them into the other projects along with the topics? Is there anything I should do now to be sure my upgrade to Flare 10 is painless?

Any advice would be appreciated.

Thanks.

[sdcinvan]

This is an excellent question. I've been using Flare for nearly a year now and have dozens of projects that share as little as a single line of text to about 40% shared content.

Today, I finally realized that I was doing it all wrong! Yes, Global Project Linking is probably the best approach.

Please take a look what I wrote in this thread: http://forums.madcapsoftware.com/viewto ... 79#p102879

Some useful URLs:
http://docs.madcapsoftware.com/FlareV10 ... gGuide.pdf
http://webhelp.madcapsoftware.com/flare ... inking.htm

Note: if you are not using v10, change the "FlareV10" with the appropriate version number.

[KJKurth]

That was very helpful. Thank you!

[NorthEast]

What about my context-sensitivity? If I create the header file and alias file in the common project, can I import them into the other projects along with the topics?

You can set up the header and alias file in the common project; but bear in mind that a target can only use a single alias file.

Therefore, you can't (easily) merge the entries from the alias from your common project with the alias file used by the the product target. After you import the header and alias file, the header file IDs will be available, but the problem is adding the alias file entries from the common alias file to the alias file used by the product target. I think the only way to do this is to open the flali file in text editor, and copy/paste the entries from one file to another. (Unless someone else has a better idea/workflow?)

[ChoccieMuffin]

If you use GPL, the linked file is copied into your target project. You can add the linked file to the target project's flail just like any other topic in your target project. Sorted!

[NorthEast]

If you use GPL, the linked file is copied into your target project. You can add the linked file to the target project's flail just like any other topic in your target project. Sorted!

I'm not sure you get the problem - the common project will have its own alias file (for its own topics), and presumably the project that you want to import the common topics into will also have its own alias file (for its own topics).

The result is that after the import you'll have two alias files, the imported alias file (mapped to the imported topics), and the alias file for the current product project (mapped to its own topics).

However, you can only set one alias file for a target, so you can't easily merge/combine the two alias files together, to use them for a single target.

[ChoccieMuffin]

When you create the source project you can include the file in its flali file so that it builds as you require.

When you import the project into another project, you can set the import filter to ignore any flali files. You can then add the imported topic files to the target project's flali file just like any other topic in the project.

Give it a go - really, it isn't a problem!

[NorthEast]

That's what I'm suggesting you avoid - i.e. having to manually set up alias entries for the imported topics in the project they're imported into, and having to repeat that for each project.

[sdcinvan]

I have some free time and I've been experimenting a bit.

In my opinion this whole external link and the GPLing is just one big, convoluted mess!

Why on Earth did MadCap opt for complicating things this way? In other words, copying external files into a local project folder and then maintaining an absolute path sync back to the parent file? You need to use the Synchronize Files feature, any time the parent file is edited.

Have you looked at the Synchronize file tool? It is ridiculous!
- It isn't clear which files need to be synchronized, there are no time/date stamps, just an arrow.
Even more alarming...it seems like the EXPORT FILES listing wants to overwrite the parent (SOURCE) images with whatever has changed in the local project folder! I NEVER want my source files overwritten!
- You cannot determine if files are still in use... to determine orphans, you will need to open another tool, MadCap Analyzer.
- It always lists every file in a project, all the time... rather than list only those files whose parent has been updated.
- For images modified in MadCap Capture... then if a parent file (image) is updated and then synchronized in Flare, there is no integration with MadCap Capture. The old images remain until the Capture's EDIT > REPLACE function is used.

It seems to me that a more elegant and simpler way to accomplish the same thing is to allow a project link dynamically to a single common source folder. No synchronization required! Any changes to external files is instantly reflected in the project... again, no synchronization required! And no duplicate files! What's more, you no longer have to wonder if any of the images are out of sync.

For 70% of my documents, I want these Flare projects to all share a common core of images, the same stylesheet (well, the entire resource folder). If I make edits to the common images or the common resources, I want those changes instantly reflected in the opened project. I don't want these common files *copied* into each project (wasting space) and subjected to convoluted synchronization.

Synchonize_files_flaws.png

Yes, I am ranting but I am only doing so because I want Flare to be a better product.

[NorthEast]

In my opinion this whole external link and the GPLing is just one big, convoluted mess!

Just to note, most of the issues you're talking about are about External Resources, which is a completely different thing to GPL which is a Project Import.
http://webhelp.madcapsoftware.com/flare ... _Files.htm

If you use a project import, combined with the setting to Auto-reimport before "Generate Output", then the files will be re-imported when you build to ensure they are up-to-date. You can override this on a per-target basis, if you want to choose when to update the files for that output.

For 70% of my documents, I want these Flare projects to all share a common core of images, the same stylesheet (well, the entire resource folder). If I make edits to the common images or the common resources, I want those changes instantly reflected in the opened project. I don't want these common files *copied* into each project (wasting space) and subjected to convoluted synchronization.

The majority of my projects use the same 'template', so I use a project import (linked to a master project on a network drive) for my common project files , e.g. stylesheets, page layouts, master pages, skins, images.

[sdcinvan]

In my opinion this whole external link and the GPLing is just one big, convoluted mess!

Just to note, most of the issues you're talking about are about External Resources, which is a completely different thing to GPL which is a Project Import.
http://webhelp.madcapsoftware.com/flare ... _Files.htm

If you use a project import, combined with the setting to Auto-reimport before "Generate Output", then the files will be re-imported when you build to ensure they are up-to-date. You can override this on a per-target basis, if you want to choose when to update the files for that output.

For 70% of my documents, I want these Flare projects to all share a common core of images, the same stylesheet (well, the entire resource folder). If I make edits to the common images or the common resources, I want those changes instantly reflected in the opened project. I don't want these common files *copied* into each project (wasting space) and subjected to convoluted synchronization.

The majority of my projects use the same 'template', so I use a project import (linked to a master project on a network drive) for my common project files , e.g. stylesheets, page layouts, master pages, skins, images.

Thank you Dave,

Unless I am misunderstanding, it seems that the whole concept of important doesn't actually solve the issues that I am criticizing. In particular, duplication of content and not having a single location for common content (that is project agnostic).

Looking at the link you provided...
Import Flare Project Wizard (Recommended) The Import Flare Project Wizard guides you through the steps for importing Flare files from another project. When you use this wizard, an import file is created automatically and placed in the Imports folder in the Project Organizer.

Again, unless I am completely missing the point, I don't want to import another project. The only things that I want to do are...
Share a common resource folder, which includes:
- Stylesheets, One of several common stylesheets (99% of my projects will use the same stylesheet)
- Images, 100% of my projects will use at least some of the same images.
This is important because some images are constantly getting updated and I want any changes to instantly reflect in every other document!
This is ALSO a problem because any images edited with Capture do not automatically update!
- MasterPages and PageLayouts (all projects share the same ones).
- Snippets, I want to maintain a single master library of Snippets for 100% of my projects.
- TableStyles - Because all my project will use the same styles.

In addition to the Resources folder, there are also a dozen or so topics that are shared with many of my projects.

It seems that with the Import Project option, I am forced to pick a project and use that as the master. That seems rather ridiculous because there is no "master project" in my library and every project I am currently working on will eventually because obsolete (which the resources folder lives on and improves).

What am I missing here?

[DocuWil]

- Images, 100% of my projects will use at least some of the same images.
This is important because some images are constantly getting updated and I want any changes to instantly reflect in every other document!
This is ALSO a problem because any images edited with Capture do not automatically update!

I should use the GPL (Global Project Linking) for this.
Go to that folder and navigate to the images folder and right-click to edit with MadCap Capture (the recapture option. I never have problems with that).
Then ..... in your "Imports file" of your project you have to set the "Auto-reimport before Generate Output" option.
I think with Snippets and TableStyles it is the same in your case.

Don't forget that if you use the Resources folder you always need to force synchronizing!

[NorthEast]

Thank you Dave,

Unless I am misunderstanding, it seems that the whole concept of important doesn't actually solve the issues that I am criticizing. In particular, duplication of content and not having a single location for common content (that is project agnostic).

Looking at the link you provided...
Import Flare Project Wizard (Recommended) The Import Flare Project Wizard guides you through the steps for importing Flare files from another project. When you use this wizard, an import file is created automatically and placed in the Imports folder in the Project Organizer.

Again, unless I am completely missing the point, I don't want to import another project. The only things that I want to do are...
Share a common resource folder, which includes:
- Stylesheets, One of several common stylesheets (99% of my projects will use the same stylesheet)
- Images, 100% of my projects will use at least some of the same images.
This is important because some images are constantly getting updated and I want any changes to instantly reflect in every other document!
This is ALSO a problem because any images edited with Capture do not automatically update!
- MasterPages and PageLayouts (all projects share the same ones).
- Snippets, I want to maintain a single master library of Snippets for 100% of my projects.
- TableStyles - Because all my project will use the same styles.

In addition to the Resources folder, there are also a dozen or so topics that are shared with many of my projects.

It seems that with the Import Project option, I am forced to pick a project and use that as the master. That seems rather ridiculous because there is no "master project" in my library and every project I am currently working on will eventually because obsolete (which the resources folder lives on and improves).

What am I missing here?

Using a project import will solve some of the issues you found with External Resources; e.g. confusion about the interface, automatic updating of imported files, and controlling the direction of import.

I use project imports for exactly what you're describing; i.e. importing 'resource' files that are common across my projects, such as stylesheets, table styles, master pages, page layouts, snippets, images, skins.

Bear in mind when you use a project import, you don't have to import an entire project, just the files from that project that you want to import; i.e. you can specify files by name, include certain file type, or files marked with a particular condition (this is what I use, I mark files that I want to import with a 'master' condition).

Anyway, I think you need to actually try it out.

[KJKurth]

WOW! I've been on vacation since Aug 22. This post sure has been busy in my absence! Thank you for all the excellent points to consider.

I'm going to use global project linking. While not perfect, it seems to be the best choice for this particular set of projects. It sure would be nice, though, if Flare gave me the option of automatically appending the lines from the common project header and alias files to the header and alias files in the all the associated projects. I need the strings and ID numbers for those common topics to be identical throughout all the associated projects so that my context-sensitive help works everywhere. Automatically updating the files would be a big help.

[sdcinvan]

WOW! I've been on vacation since Aug 22. This post sure has been busy in my absence! Thank you for all the excellent points to consider.

I'm going to use global project linking. While not perfect, it seems to be the best choice for this particular set of projects. It sure would be nice, though, if Flare gave me the option of automatically appending the lines from the common project header and alias files to the header and alias files in the all the associated projects.

I think I hijacked your post. Sorry... this issue is such a concern to me that I thought I was the OP.

I need the strings and ID numbers for those common topics to be identical throughout all the associated projects so that my context-sensitive help works everywhere. Automatically updating the files would be a big help.

It appears that you/I have similar requirements. Context sensitive help is also on my plate, to be implemented within two months. I am very concerned about how this will work with Global Project Linking and revision control. On the surface, without fully understanding all through concepts, I fear a very messy implementation.

Question to all:
Is anyone else successfully combining Flare projects with:
- Building context sensitive help documents
- Documentation revision control (especially git - though it isn't currently directly supported in Flare)
- Global Project Linking

If so, any tips or best practices will be appreciated.

Thanks all,
Shawn

[KJKurth]

No worries about hijacking the post. I'm enjoying the discussion and it's giving me tons of good info that I can use when making decisions on this project and other, upcoming ones.

[DocuWil]

You can have a look in the following post how I use Global Project Linking:
http://forums.madcapsoftware.com/viewto ... 13&t=12331

[KJKurth]

Very interesting and informative. Thank you!

[sdcinvan]

Yes, thank you Wil!

Another informative post on global project linking.

MadCap needs to do a webinar on this topic. In my opinion, this is one of the least known, yet one of the most important Flare topics that many of us should understand.

As well as global project linking, MadCap also needs to do a webinar on revision control (specific to which tools Flare works with and generic concepts).... another extremely essential topic for many MadCap Flare users.