One Project or Many?

[AndrewCampbell]

I've just taken over a few Flare projects. Each one is for a different product at my company. They all use the same CSS and page layouts and so on.

I am thinking of combining them all into one project. This has the advantage that I just have to update the CSS and page layouts in one place, and it allows for content re-use.

I was wondering what the disadvantages of this approach are. For example, could I use lingo to send a subset of my content to a translator, or does Lingo send all the content in a project?

[RamonS]

The advantage of having a CSS or page layout in only one place is appealing, but you can accomplish the same by copying the files from one project to the others assuming the file names are the same. What you gain then is keeping content separate with ease. If you stuff everything into one project you need to apply conditions and craft multiple targets to get the desired output. That may be beneficial if the projects share a lot of content. If not, you trade convenience of editing two items with a nightmare of managing multiple sets of conditions and having to apply them painstakingly each time you add something. One accident and you end up with content for product A in the output for product B. I'd keep the various projects.

[wclass]

If the help is needed for different products, I would suggest separate projects for each, but keep your common files, like CSS, master pages, etc, in a global project/template and just import the common files in as needed using Global Project Linking.
Read up on GPL : http://help.madcapsoftware.com/flare201 ... inking.htm

[AndrewCampbell]

The advantage of having a CSS or page layout in only one place is appealing, but you can accomplish the same by copying the files from one project to the others assuming the file names are the same.

No, you can't accomplish the same. Unless you and all your colleagues are unnaturally disciplined, the CSS and associated files will drift apart in time, either because someone forgot to update it in one of the thirty or so projects you have, or because someone made one small change for 'just this project'.

I'm currently working with a situation where my predecessors allowed the CSS and associated files to drift apart, and I am trying to make that impossible for the future.

What you gain then is keeping content separate with ease. If you stuff everything into one project you need to apply conditions and craft multiple targets to get the desired output. That may be beneficial if the projects share a lot of content. If not, you trade convenience of editing two items with a nightmare of managing multiple sets of conditions and having to apply them painstakingly each time you add something. One accident and you end up with content for product A in the output for product B. I'd keep the various projects.

You do not need to use conditions to exclude content from output. If all of your output contains all of your unconditional content you are doing something very wrong.

[AndrewCampbell]

If the help is needed for different products, I would suggest separate projects for each, but keep your common files, like CSS, master pages, etc, in a global project/template and just import the common files in as needed using Global Project Linking.
Read up on GPL : http://help.madcapsoftware.com/flare201 ... inking.htm

What advantage do you have when you split the different products into different projects? Global project linking has a few overheads that I don't want to introduce without knowing about the advantages.

[Nita Beck]

What advantage do you have when you split the different products into different projects? Global project linking has a few overheads that I don't want to introduce without knowing about the advantages.

As Margaret says, with global project linking, the corporate-level stuff that you want to lock down would be maintained in a corporate-level project (aka a global or parent project). You can enforce a policy that only a certain author or authors are allowed to make changes to things in that project. Then, you'd have the product-level projects (aka child projects) import and use the files from the corporate-level project; the authors of the product-level projects would not change those files, only use them.

There have been many discussions on the forums over the years about the benefits of GPL and strategies for organizing files.

A best practice is to carefully organize content in all projects and to carefully name folders so that it is practically self-evident what comes from where.

For my global projects, I organize my Content Explorer like this:

Code: Select all

Content
   GLB
      GLB_Images
      GLB_Resources
      GLB_Topics

For a child project, I organize my Content Explorer like this (where PA in this example means "Product A"; this shows how it looks prior to the first import from GLB):

Code: Select all

Content
   PA
      PA_Images
      PA_Resources
      PA_Topics

After the import from GLB, I end up with this:

Code: Select all

Content
   GLB
      GLB_Images
      GLB_Resources
      GLB_Topics
   PA
      PA_Images
      PA_Resources
      PA_Topics

The beauty of this arrangement is that I (and my co-authors) almost instinctively know that we can mess around all we want with the stuff within the PA folder, but we know not to edit any of the stuff in the GLB folder. If it becomes clear that a global file needs to be edited, we can edit it in the global project (assuming we have authority) or speak to the author who has authority to make changes. Once the changes are made, we then re-import files into the child project.

Re the global files that end up in the Project Organizer, because they will intermingle with the child project's files, I advocate naming conventions to indicate that something comes from the global project. So say there is a variable set that gets imported; I will have named that GLB_Variables. (And then, if I need a local variable set, I'll name it PA_Variables. The naming convention can help one to know which files are hands-off and which files are freely editable within the child project.)

HTH. If you already knew all this stuff, my apology. I tend to answer questions for the whole forum community, not just the OP.

[AndrewCampbell]

As Margaret says, with global project linking, the corporate-level stuff that you want to lock down would be maintained in a corporate-level project (aka a global or parent project). You can enforce a policy that only a certain author or authors are allowed to make changes to things in that project. Then, you'd have the product-level projects (aka child projects) import and use the files from the corporate-level project; the authors of the product-level projects would not change those files, only use them.

This is an appealing advantage. Is the policy enforced by Flare, or does it have to be enforced some other way? For example, if an unprivileged user has both the parent project and the child project, does Flare stop them editing the parent project?

[Nita Beck]

Yes, an author having both the global project and child project on their computer could indeed edit the global project.

By "policy," I don't mean anything that is controlled by Flare. Rather, you have to establish a policy with your authoring team. "If you are not authorized to modify corporate-level stuff, don't!"

Without seeming to go off topic, I hope that you are also using source control. With a source control system in place, were a non-authorized author to modify corporate-level stuff, in violation of departmental policies, you could view the history of the global project in your source control tool to determine who made the change, when they made the change, and exactly what they changed -- and you could roll back to a point prior to the change, and then go chide that non-authorized author...

(Hmmm, it occurs to me that it *might* be possible in some source control tools to lock down the global project there, that only certain authors can commit changes, with all other authors only being able to read the repository. This is a guess on my part. I've not ever worked with source control that way.)

On the teams that I work on that use global project linking, a lot of communication goes on among the team regarding modifications needed to the global project. A team ends up becoming "sensitized" to the ramifications of modifying the global project, even by authorized authors. We all tend to "think globally" when contemplating a modification. We stop and think things like, "OK, I want to change the XYZ table style so that it works in my product project, but how might that affect my colleagues' projects?" Pausing to think about the ramifications ends up spawning conversation with one's colleagues, which I think is exactly how a team needs to operate. In some cases, there will be no question that something needs to change globally, like when marketing dictates new branding colors or a new corporate font; obviously, the global files will need to change and then be re-imported in all the product projects.

[AndrewCampbell]

By "policy," I don't mean anything that is controlled by Flare. Rather, you have to establish a policy with your authoring team. "If you are not authorized to modify corporate-level stuff, don't!"

From my point of view, that severely mitigates the benefit of GPL. A policy of "don't touch the global project" is as easy to enforce as "don't touch these folders..."

Can I turn my question around and ask what are the drawbacks to having all the documentation across the whole product suite in one project?

Without seeming to go off topic, I hope that you are also using source control.

Oh yes

I'm going to try to take a few hours to play with GPL and see if I like how it works. I've worked with similar systems in the past, and they have always been relatively clunky when used in the way that I need to use them. GPL may be different.

[NorthEast]

You do not need to use conditions to exclude content from output. If all of your output contains all of your unconditional content you are doing something very wrong.

If you plan to combine projects (for each product) together into a single project, then I'm pretty sure you're going to have to use conditions.
If you want to build separate targets for each product, then you'll need to use conditions to exclude content for other products.

This is an appealing advantage. Is the policy enforced by Flare, or does it have to be enforced some other way? For example, if an unprivileged user has both the parent project and the child project, does Flare stop them editing the parent project?

Flare doesn't enforce/prevent anything, it'll require some education and common sense by the people using it.

A project import just copies files from one project to the current project, so the copied files are part of the current project. If you try and edit an imported file, Flare will warn you that it's from an import. However, you can still carry on and update the file, or even unlink it from the import so it's no longer updated.

[AndrewCampbell]

If you plan to combine projects (for each product) together into a single project, then I'm pretty sure you're going to have to use conditions.
If you want to build separate targets for each product, then you'll need to use conditions to exclude content for other products.

I'm not sure what you mean by this.

If I am generating a PDF from a project, then only the files in the TOC will find their way into the PDF. If I am generating HTML5 from a project then by default all of the content will be copied into the final output, but it is trivial to disable this without using conditions (In the project explorer, double click the target. Select the Advanced tab and check the "Exclude content not linked directly or indirectly from the target" checkbox.).

[Nita Beck]

If I am generating a PDF from a project, then only the files in the TOC will find their way into the PDF. If I am generating HTML5 from a project then by default all of the content will be copied into the final output, but it is trivial to disable this without using conditions (In the project explorer, double click the target. Select the Advanced tab and check the "Exclude content not linked directly or indirectly from the target" checkbox.).

I can practically guarantee that there will be content *within* topics that are included in both PDF and HTML5 outputs that is meant only for PDF or only for HTML5. So in order to keep the "PDF only" stuff out of topics shared with your HTML5 target, you will need to exclude it from the HTML5 target. In order to keep "HTML5 only" stuff out of the topics shared with your PDF target, you will need to exclude it from the PDF target.

Furthermore, if there's a project that supports multiple products, there is likely to be content *within* topics that applies to one product but not another product. Solution? Conditions...

[AndrewCampbell]

I can practically guarantee that there will be content *within* topics that are included in both PDF and HTML5 outputs that is meant only for PDF or only for HTML5. So in order to keep the "PDF only" stuff out of topics shared with your HTML5 target, you will need to exclude it from the HTML5 target. In order to keep "HTML5 only" stuff out of the topics shared with your PDF target, you will need to exclude it from the PDF target.

Yes, in those situations you will need to use conditions in some way, but if I have two documents for one product (or even two documents for two products) in one project, the content for document 1 won't end up in document 2, unless something has gone badly wrong.

(I come from a DocBook and DITA background, and I think there are better ways to deal with "PDF only" stuff than using conditions, but that is another topic.)

[NorthEast]

If I am generating HTML5 from a project then by default all of the content will be copied into the final output, but it is trivial to disable this without using conditions (In the project explorer, double click the target. Select the Advanced tab and check the "Exclude content not linked directly or indirectly from the target" checkbox.).

Yep, if that setting works for you, then by all means use it.
It's not a feature we can use in any of our projects because not everything has a direct link, and Flare can't see links in scripts.

It'd be fairly trivial to use conditions too - e.g. put the content for each product in separate folders, then set a condition on the folder.
There's a lot of advantages in using conditions generally, especially if you have any shared content between the products.

[Nita Beck]

It'd be fairly trivial to use conditions too - e.g. put the content for each product in separate folders, then set a condition on the folder.

Yep, this is exactly how I organize projects that support multiple products.

[AndrewCampbell]

It'd be fairly trivial to use conditions too - e.g. put the content for each product in separate folders, then set a condition on the folder.

What advantage does that offer over, say, multiple ToCs?

[Nita Beck]

It's not that having product-specific stuff in their own conditioned folders is in lieu of multiple TOCs. It's not. Rather, it is insurance that nothing goes "very wrong" as you alluded to above. If all the Product B files (topics, particularly) are segregated in their own folder, then it's very, very easy to condition that entire folder for Product B only. That way, it's very, very easy to keep the Product B topics out of Product A targets (of any output type) by excluding Product B only stuff at the target level.

[AndrewCampbell]

It's not that having product-specific stuff in their own conditioned folders is in lieu of multiple TOCs. It's not. Rather, it is insurance that nothing goes "very wrong" as you alluded to above. If all the Product B files (topics, particularly) are segregated in their own folder, then it's very, very easy to condition that entire folder for Product B only. That way, it's very, very easy to keep the Product B topics out of Product A targets (of any output type) by excluding Product B only stuff at the target level.

OK, its a belt-and-braces approach? I can understand that

I've recently encountered some very bad use of conditions to exclude content. If there was a "Flare Horror Stories" forum I'd post them there.

[Nita Beck]

I've recently encountered some very bad use of conditions to exclude content. If there was a "Flare Horror Stories" forum I'd post them there.

Conditions can indeed be badly mismanaged and misapplied. My design philosophy for *anything* within a Flare project, not just its conditioning strategy, is to seek the simplest solution possible.

Product structure can also be badly done. I believe in tidy projects. In my projects that support multiple products but that also import from a global project, I end up with a Content Explorer something like this. (Notice, I've used leading underscores to push some folders to the top.)

Code: Select all

Content
   _GLB
      ...
   _Shared /*For content that is local to the project but is shared by all the products; this is not conditioned at the folder level */
      ...
   PA /* For Product A content and conditioned as ProductAOnly */
      ...
   PB /* For Product B content and conditioned as ProductBOnly */
      ...
   

HTH. I've enjoyed our conversation. Now it's time to hit the gym!!