Linked projects or multiple targets?

[BedfordWriter]

Here's a philosophical question for you: Given...
a) a large set of documentation files,
b) a need to create several course workbooks,
c) and also how-to documents for various product features,
d) where those workbooks and how-to documents will contain some content that's in the documentation and some that's unique
...would you tend to use linked projects or targets within one project?

I can see relative advantages to each approach, but I'm curious whether anyone has a guideline to say "in this case, use a new target within the original project" and "after this threshold use a linked project". Which approach do you take?

[NorthEast]

Well, Flare is designed for single sourcing, so I always try to have a single source (project) where possible.

So for a set of documentation that has shared content, my first approach would always be to put everything in one project and have multiple targets.

If things change and that approach isn't working for some reason, then it's not difficult to split a large project into separate projects, or make a copy of the project if you need to have separate branches.


It's a lot harder to work the other way around; e.g. start off with a number of projects, and then have the headache of trying to import/combine them together.

Separate projects work a lot better when the content is actually separate (which may be its content, or its ownership/management).
If you're merging/combining/importing projects, then you probably need to review whether the projects should be separate.

[Nita Beck]

Hi, my MadWorld friend!

If the large set of documentation files are about the same subject/product or very closely related subjects/products, I would opt for one large Flare project. With a thoughtful architecture, even a very large Flare project that produces many targets for different subjects/products can be easy to maintain and to extend.

If the large set of documentation files are about different subjects/products but all need to have the same "look and feel" and a small set of shared content, then I *might* opt for a parent project to hold the "corporate level" stuff (e.g., stylesheets, "corporate" content such as legal material, page layotus) and separate child projects, one for each subject/product and which imports the "corporate level" stuff from the parent project.

I do agree with Dave for the reasons he states. I think I'd start out with one project. In future, if you decide to split it up, that's easy enough to do with the Export feature. Definitely easier to split up then to consolidate.

[BedfordWriter]

Very good input, and I greatly appreciate both responses. The single project route is the one that I'm leaning toward, but I was questioning my choice.

As Nita suggests, it's a matter of percentage. If 90% of the information for an output is unique to that output, and 10% matches the main project AND must match the current version of the main project, then linking might be appropriate. On the other hand, if only 10% is unique to said output, then it doesn't hurt to tuck it away in the main project, using conditionals so that it doesn't show up in any of the other outputs.

I'm thinking that it might be subjective, this question of where one draws the line. Any further thoughts?

[ChoccieMuffin]

If you have several sets of stuff, where each group shares loads of stuff internally but not a lot with other groups, then I would go for separate groups. For example:

Product 1 outputs:
Beginner's guide
Expert's guide
Tutorial
Reference guide
Help file

Product 2 outputs:
Beginner's guide
Expert's guide
Tutorial
Reference guide
Help file

Corporate stuff (to go in everything):
Stylesheets
Copyright text
Other standard text
Standard images
Page layouts
Master pages

In the above very simple setup I would have three Flare projects, with Product 1 and Product 2 using Global Product Linking to import the corporate stuff. Works a treat and means that you maintain ONE stylesheet and other corporate stuff, and keep all your look-and-feel, marketingy, fluffy stuff in one place.

To add a bit of complexity, imagine that you have ten products and a couple of widgets. Some products include Widget 1, some include Widget 2, some use both widgets, some use neither, and both widgets need to produce widget-only documentation.

In this situation would create separate projects for Widget 1 and Widget 2, both of which use GPL to import from the Corporate Flare project. I would then include .flimpfl files in each of the products that require imports from Widget 1 and Widget 2, being careful that you don't include any of the corporate stuff in your imports, so your products just get the stylesheet that lives in the corporate project.

This is the documentation set I work with - 34 separate projects most with several outputs, a single project containing corporate stuff that imports into everything else, some of those 34 are "solo" projects but are also imported into other projects. It's a total nightmare when it comes to release deadlines because we have to produce a full set of documentation and help for the whole darn lot. (I haven't done a page count or wordcount on our outputs, that would be far too frightening, but at a guess it's about 50,000 pages.)

Flare is so strong in that respect

[charleybrown]

Hi!

Interesting thread! We are currently facing the same decision, so this has been very valuable. To chime in: thinking about one gigantic Flare project with potentially tends of thousands of topics and hundreds of targets makes me worry about performance for the people actually using this project in Flare. Do you have any experience as to when to expect performance degradation? How much content can Flare support confidently without becoming too slow to work in?

[ajturnersurrey]

How easy depends on your computing power and the way any files are shared. I have a mixture of both approaches in my work.
I am on a windows10 i7 laptop with 8GB RAM and work on my project files over the work network. I have a project that produces my top-level 300 page generic software manuals, which has about 7300 files in the Content folder (mainly topics, snippets and images) and works fine, although there are one or two noticeably slow, super-long topics (with lots of conditions and cross-references) within that project. As a counter example, I have a self-contained project, which imports some of those files as a base, in order to produce application notes, and it only has about 2600 files in the Content folder. It is noticeably quicker to work with.

[Psider]

I'm following this thread with interest. Thanks everyone.

A question I'm interested in is the case of multiple authors. Do you guys split projects so that multiple people can work on different segments at the same time? Or do you somehow manage this with a single project? How do you manage conflicts with a single project - folder structure? close communication? source control merge tools?

[NorthEast]

I'm following this thread with interest. Thanks everyone. :)

A question I'm interested in is the case of multiple authors. Do you guys split projects so that multiple people can work on different segments at the same time? Or do you somehow manage this with a single project? How do you manage conflicts with a single project - folder structure? close communication? source control merge tools?

Use source control.
If you have multiple authors then using source control is essential, whether you have a single project or multiple projects.

[SteveS]

^^^ What he said!

If you have multiple authors on the same project you need some form of source control.

[Psider]

So for multiple authors on a single project, you don't worry about if two people modify the same topic at the same time? Do you just use the source control merge tools? Or you stop and have a discussion about which bits of each change should go in?

Or do you say "You work on folder X topics only. If you need to make changes in folder Y you let me know and I'll make those changes."?

And I assume that because Flare just works on what's in the directory structure, you don't have the same problems as Robohelp "knowing" about different additions/deletions for different users (caused by the .cpd database indexing different files for each user)...?

[NorthEast]

So for multiple authors on a single project, you don't worry about if two people modify the same topic at the same time? Do you just use the source control merge tools? Or you stop and have a discussion about which bits of each change should go in?

Or do you say "You work on folder X topics only. If you need to make changes in folder Y you let me know and I'll make those changes."?

And I assume that because Flare just works on what's in the directory structure, you don't have the same problems as Robohelp "knowing" about different additions/deletions for different users (caused by the .cpd database indexing different files for each user)...?

You can see if a topic/file is already checked-out to someone else, so I usually just ask them if they've finished and can check it in.

If you both edit a file, then yes you have to merge the changes together, but we tend to avoid ever getting into that position.

You can help avoid that by using the setting in Options to Lock files when automatically checking out.

But even if you mess things up, the benefit of source control is that you can always go back to a previous versions of the file.

[Psider]

Thanks for that. Just trying to get a feel for how single project/multiple authors works, as I've always been in the situation of single author per project.

[MAF]

Hello all,

I'm digging out this old thread because my company is currently trying to find a solution to implement search feature across many flare projects. Of course, we are using topnav html5 which means that all server based and project merging features. Also, web crawlers are not allowed on our production servers, so Google Custom Search Engine is not an option either.

Our main problem is that some of our projects are in several languages... but not all. e.g. technical guides could be in English only while user guides could be in French and English. Practically, this implies that making a big unique project out of these separate projects would be a (very) painful solution as the non-translated content would have to be removed manually from the translated versions of the big project... each time we make a new translation with Lingo.

Today, the only solution I see is to make a big project that imports individually my single projects... I then "translate" this big project (which has no content of its own), and for each translated version of this big project, I modify the project imports to point toward the translated versions of the single projects. For projects which don't have a translation, I link them to original language project with a small warning saying that translation does not exist for that topic (which is awful but that's what Microsoft does for example).

All this seems extremely painful for just a workaround for a feature that really should exist in Flare i.e. Enabling runtime merging for TopNav Html5. I think we all agree that an efficient search
function is one of the main features expected from a modern web based help (what good is a doc nobody can find)!

Therefore my main question is: Do we have any information about when this feature will be released? Companys like yours and mine are spending time and money to implement workarounds (and browsing forums ) and the posts I can see on this subject start way back in 2015...

MAF

[eclecticbanana]

Hello all,

I'm digging out this old thread because my company is currently trying to find a solution to implement search feature across many flare projects. Of course, we are using topnav html5 which means that all server based and project merging features. Also, web crawlers are not allowed on our production servers, so Google Custom Search Engine is not an option either.

Our main problem is that some of our projects are in several languages... but not all. e.g. technical guides could be in English only while user guides could be in French and English. Practically, this implies that making a big unique project out of these separate projects would be a (very) painful solution as the non-translated content would have to be removed manually from the translated versions of the big project... each time we make a new translation with Lingo.

Today, the only solution I see is to make a big project that imports individually my single projects... I then "translate" this big project (which has no content of its own), and for each translated version of this big project, I modify the project imports to point toward the translated versions of the single projects. For projects which don't have a translation, I link them to original language project with a small warning saying that translation does not exist for that topic (which is awful but that's what Microsoft does for example).

All this seems extremely painful for just a workaround for a feature that really should exist in Flare i.e. Enabling runtime merging for TopNav Html5. I think we all agree that an efficient search
function is one of the main features expected from a modern web based help (what good is a doc nobody can find)!

Therefore my main question is: Do we have any information about when this feature will be released? Companys like yours and mine are spending time and money to implement workarounds (and browsing forums ) and the posts I can see on this subject start way back in 2015...

MAF

Have you considered merging everything into one project and then wrapping content for each language in conditions? I may be misunderstanding, but I think that I do something similar for multiple products. Example below.

The Flare project, called Project, contains documents for five products. Product 1 has Document A, B, and C. Product 2 has Document A, B, and C. And so on.

Each document set for each product is wrapped in a condition. Product 1's documents are wrapped in Condition 1. Product 2's documents are wrapped in Condition 2. And so on.

Each document set for each product has a target that excludes conditions for every other product's documentation set. Product 1's target excludes all content that isn't wrapped in Condition 1. Product 2's target excludes all content that isn't wrapped in Condition 2. And so on.

This means that:

• All available content for a product is searchable in that product's online help.
• Content for other products is excluded when searching a specific product's online help.
• I have one project for every product, and only have to manage one set of CSS, page layouts, masterpages, variables, etc.

[MAF]

Thanks for your reply eclecticbanana!

I think your perfectly right, going for a big single project is definitely the way to go. I found Dave Lee's contribution to this post very enlightening and it made me realize that it is a golden rule to put shared content in a single project as much as possible... Projects imports are cool but rapidly show their limits!

As for the rest of your solution, that is basically what I would do if I wanted separate outputs (but IMHO it would be simpler just with different TOC instead of conditions).

The bad news is that I DO want a single output to have a federated, cross products search... And this where it gets ugly with translation.
The good news is that I think I found a solution for my HTML Top Nav:

1. I merge all my separate content in one single project
2. I create a condition named "NotTranslated"
3. I create a snippet saying "sorry this topic is not available in this language" in a warning style and I insert it in my master page with a "NotTranslated" condition
4. I import this big single project into lingo and translate only topics I need translated and the snippet created in step 3.
5. I export the big file from lingo into a translated version
6. in the translated version, I select the "NotTranslated" condition for all untranslated topics in the TOC (using apply property on multi-selection)
7. I go back to my original project, add the translated project in the language tab and build it

This way, I have one unique output with a search box that can search all my project (which is what my boss wants) and I have the magic "change language" button to switch to other languages. If I hit that button while I am on a topic which doesn't have a translation, I will get the same topic in the original language with a warning message saying it's not available in this other language.

This is the simplest I found for dealing with the incomplete translation problem in one single project. I have yet to implement it (next sprint hopefully), I'll tell you how it goes, but I cannot see any obvious flaw in the plan. If you can think of something simpler, I'm all ears

MAF