Best way to store multiple related projects?

[ccardimon]

If yo have multiple project that are separate, but related, how do you folks "arrange" them in Flare?

Do you create separate projects for each, or do you house them under one project title and branch out from there?

[techwriter31]

Long answer - We have a lot of different hardware product lines with varying models within each product line. Each product line is unique, but also shares similar functionality between the other product lines. We also translate all of our hardware documentation, and this had a huge impact in regards to how I decided to implement our Flare project structure. My main goals were to reduce English documentation time and duplication of effort (previously, one hardware change could result in making the same change in 5 or more locations), to reduce in-house translation time, and to reduce overall translation costs.

Here's how we manage them:
- We create a new Flare project for each product line.
- We have a single "Global" English project that stores all of the shared content (images, stylesheets, page layouts, skins, snippets, conditions, etc.). We then import this content into the local "child" projects.
- Per Nita Beck's recommendation a few years back - within the Global project, all folders in the Content Explorer have been renamed to "Global_Content", "Global_Resources" and "Global_Images". Then, in all of the child projects, we name the folders "xxxx_Content", "xxxx_Resources" and "xxxx_Images". This has really helped, because when you import the content into the child projects, you can quickly see what is global and what is local in the child projects. This would also be really useful when importing from one child project to another, but I found that for our purposes, importing between child projects got a little complicated.
- We have one English stylesheet in the global project with mediums defined for 8"x11" print, 4.75"x4.75" print, online and mobile. We also have a different stylesheet for each language that we translate to, but we reference the English stylesheet as an import and only include translated auto-text in these stylesheets. Then, when we translate these projects, the vendor just specfies the translated stylesheet as the Master Stylesheet in the target, and all of our notes/cautions, cross-references, figure caption and table caption text is already translated and included in the output.
- The snippets in the Global project are primarily just boiler-plate regulatory text, or text that occurs frequently throughout the child projects. If we include snippets in the child projects, it is because they are unique to that product line, and are stored under "xxxx_Resources\Snippets" folder.
- We have a single conditional tag set for all outputs that is stored in the Global project and imported into the local projects.
- All images in the Global project contain no text, and are typically regulatory images (CE, FCC, etc.) or images used for TOC icons in our online outputs.

Hope this helps!
------------------

Then, in all of the child projects, we name the folders "xxxx_Content", "xxxx_Resources" and "xxxx_Images".

EDIT: This should state "xxxx_Topics" and not "xxxx_Content".

[Nita Beck]

Kellie,

Thanks for the shout-out re my recommendations for naming folders in a global project and child projects.

But thanks also for explaining how you're handling the stylesheets, especially the main English stylesheet and the language stylesheets that import it. What a great idea! I will soon be working with one of my clients to plan out the localization strategy for a global project and several child projects. Eventually there will be translations into 10-12 languages. What you've described makes me think that we need to rethink our stylesheets, now, before we're in the throes of a localization.

Smart, smart, smart!

Thanks!

[techwriter31]

Thanks Nita!

No problem! Renaming the folders really helped me because I was worried that it might be hard for our other writers to quickly determine what content was imported and what was local. The only issues I've run into with using the custom folders are:
1) Flare defaults to the standard Resources\Snippets folder when creating snippets, so you always have to re-specify the custom folder when adding a new snippet to the project. I submitted an enhancement request to allow you to specify/set the default folder location that you want to save to.
2) If the stylesheets aren't stored in the default Resources\Snippets folder and you generate a WebhelpPlus or HTML5 output, the stylesheets are actually included in the search results. I've submitted an enhancement request to exclude these items from the search results.

Yes, the translated stylesheets have helped a lot! In addition to translations, it allows us to also apply formatting for specific languages. For example, for our Japanese translations, we never want to use italics. In the past, we always specified this for each translation project, but the majority of the time it still came back with italics. So, in the Japanese stylesheet, I just set the "i" tag to use a normal font style and weight, and now we no longer have to worry about it. The only problem I've had is remembering to update the translated stylesheets when updating the English...

Overall, we have significantly reduced our translation costs after switching to Flare and implementing single-sourcing. It has also saved my sanity, as I'm no longer tracking/making the same changes to numerous documents.

[hjord]

Hi, do you perhaps have a link to the original post with the recommendations by Nita Beck? I'd really like to read that as I have similar issues.

[techwriter31]

Hi, do you perhaps have a link to the original post with the recommendations by Nita Beck? I'd really like to read that as I have similar issues.

Found it!
http://forums.madcapsoftware.com/viewto ... it=+Global

[Msquared]

Techwriter31

I've just read this with interest. I'm in the act of setting up our Flare environment for a move to Flare. Like you I have identified some global content (conditions, variables, stylesheets etc), but I was planning to put all that in a global project, then use global project linking to pick that up from the other projects as required.

If I'm understanding this correctly, that isn't the approach you've taken. You're doings a straight import, which is different? I wanted to check, since I wasn't planning to rename my folders as you mention here, although I will most certainly do so if your advice applies to my situation too.

many thanks in anticipation from a Flare newbie.

[techwriter31]

Hi Msquared,

I'm sorry for the confusion! We are using Global Project Linking to import content from our "Global" project into the other projects. Nowadays, I tend to think of it as an "import" because we use the Flare import files to re-import the content.

As I mentioned, renaming the folders really helped despite the few issues I've found. AND there was a typo in my previous post! When using this structure, our folders appear as:
xxxx_Images
xxxx_Resources
xxxx_Topics
Global_Images
Global_Resources
Global_Topics

(Where "xxxx" is the product identifier. For consistency, we also name the project itself based on the same product identifier and add a language identifier. For example, "xxxx_EN.flprj".)

I had previously set up test projects using the standard folder names, but found it hard to quickly identify which files were imported from the Global project. I found it even more difficult when importing from one child project to another child project, because the only identifiers were the conditional tags and the little "import" icon that appears next to imported content when NOT in the split-pane Content Explorer view.

I also wanted it to be easy for our other writers to quickly identify which content was imported, because if it was hard for me (and I had set up the projects!), it would be even harder for others. So, in our child projects, I also renamed the folders to use xxxx_Topics/xxxx_Resources/xxxx_Images so that if we also want to do a child-to-child import, we can quickly see where that content is coming from.

[Nita Beck]

xxxx_Images
xxxx_Resources
xxxx_Topics
Global_Images
Global_Resources
Global_Topics

Ooh, Kellie, you and I are SO on the same wavelength with how our brains work! This is what I do, too, when I have a Global project (except that I abbreviate the "identifier" as "GLB_") and several child projects that import from it AND from each other. You are absolutely right that, that way, one can see practically at a glance where something came from. I don't bother with the child project identifiers when I've got a scheme in which the child projects only ever import from the Global project but never from each other.

FWIW, I also use the project identifiers "GLB_" on certain select files, such as the stylesheets that originate in the Global project. I'm all for using these kinds of "sign posts" wherever they can help authors to see where something originates and (usually but not always) where it should be maintained.

[Msquared]

Thank you so much Nita and Kellie.

I'm still in the act of trying things out before I set up my first real project very soon. I've already gone partly down the route you suggest by naming the items I have identified as global so far with names that start with "GLOBAL". Like you both, I like things to be really visible and obvious wherever possible.

It looks like I better get my head round global project linking sooner than later!

As well as a Global project, I'm also planning a Shared project. The global project will contain things that are truly global across most or all projects (some conditionals, variables, page layouts, web skins, style sheets, snippets for boilerplate text etc) and the Shared project will contain anything that is used in more than one project but isn't really global (for example, topics common to more than one project).

The thinking behind this is that at present, we have multiple documents and one on-line help file (which is based on one of the documents, but not even single sourced yet!). So I'm planning to start off by mapping each document to one Flare project. But I can see that in the future, Flare's topic-based capabilities will allow us to create a better document set, perhaps decomposed differently from our existing structure, which was a consequence of the need to bundle our content into Word documents.

So the Shared project is somewhere to put any topic (or other content) that turns out to be used in more than one place, and I can populate it as I go. Or that's the idea anyway.

Marjorie

[sdcinvan]

Hello all,

Another great post on global project linking.

I am trying to wrap my head around GPL.

Questions:
1. I have a project which I what to use as a master document (called 770-00xxx_shortdocs) - It is actually eight PDF/Web docs but the resources are perfected for any future doc).
....Based upon everything I read, I am guessing the best way to prepare this project is to do the following steps:
....a) Export 770-00xxx_shortdocs to a new project called: Glb_project
....b) Open Glb_projects and rename folders: images, resources, and reusable topic folders by appending glb_ to their folder names
....c) Because 770-00xxx_shortdocs is actually a living project, next I will delete this project and create a new default flare project, called 770-00xxx_shortdocs
.......Then I will Import > Flare Project > Glb_project
....d) Now my new 770-00xxx_shortdocs is now global project linked to Glb_project - Does this make sense?

2. Assuming the above is correct, what happens when resources are edited in 770-00xxx_shortdocs? I want those changes to automatically update in the Glb_project.
....And conversely, what if images in the Glb_project are updated? I think this is handled in the Target by checking, Automatically get latest version of all files before generating the target. Correct?
....BUT by checking that box, it works against changes made in 770-00xxx_shortdocs. I would have to ensure any changes made in the working project would have to be synced with the global project before publishing.

So what I am saying, is that Glb_project will have image updates and 770-00xxx_shortdocs will occasionally see stylesheet (and other resource) tweaks. I am just wondering how that will complicate the file syncs.

Did I get this correct?

What else should I consider?

To review, my planned file hierarchy is something like this:
>Flare Projects
....>Glb_project (global project for which all other projects are based upon/imported)
....>xxx-xxxx-Project (xxx - catalog number)
...................>content>glb_resources
...................>content>glb_images
...................>content>glb_topics

Thanks a lot everyone

[techwriter31]

2. Assuming the above is correct, what happens when resources are edited in 770-00xxx_shortdocs? I want those changes to automatically update in the Glb_project.
....And conversely, what if images in the Glb_project are updated? I think this is handled in the Target by checking, Automatically get latest version of all files before generating the target. Correct?
....BUT by checking that box, it works against changes made in 770-00xxx_shortdocs. I would have to ensure any changes made in the working project would have to be synced with the global project before publishing.

So what I am saying, is that Glb_project will have image updates and 770-00xxx_shortdocs will occasionally see stylesheet (and other resource) tweaks. I am just wondering how that will complicate the file syncs.

Global project linking is really a one-way street. The files that are common to all projects would be stored in the Glb_project and should only be edited in the Glb_project. The files stored in the Glb_project are then imported into the child projects. When imported to the child project, the file/folder structure is the same as the Glb_project, and these files include a "lock" icon to indicate they are imported. Within the child project, if you attempt to edit an imported file, a warning dialog is displayed. If you proceed with making the edits anyway, the next time you reimport from the Glb_project, these changes are overwritten. So the work flow is to: 1) Make changes to global content in the Glb_project; 2) Launch the child project and import the modified content.

Within the child project, you can import content from the Glb_project in the following ways:
1) Manually by opening the import file and clicking the Reimport button.
2) Automatically by selecting the "Auto-reimport before "Generate Output" option in the import file.
3) Automatically by selecting the "Automatically get latest version..." option in the target file.

In all cases, the files to be reimported need to be writeable or the import will silently fail.
-If the project is bound to version control within Flare, Flare will automatically check these files out and overwrite them with the updated content.
-If the project is not bound to source control within Flare, you will need to make sure the files are locked/checked out (and thus writeable) prior to import. In addition, if ANY of the files to be imported are read-only, the import will also silently fail for all files. In this scenario, I would not recommend using the Auto import options unless the workflow includes locking/checking out all global import files prior to generating the output. I filed a bug about this last week.
-If the files to be reimported are not under version control at all, and always writeable, this shouldn't be an issue.

[sdcinvan]

2. Assuming the above is correct, what happens when resources are edited in 770-00xxx_shortdocs? I want those changes to automatically update in the Glb_project.
....And conversely, what if images in the Glb_project are updated? I think this is handled in the Target by checking, Automatically get latest version of all files before generating the target. Correct?
....BUT by checking that box, it works against changes made in 770-00xxx_shortdocs. I would have to ensure any changes made in the working project would have to be synced with the global project before publishing.

So what I am saying, is that Glb_project will have image updates and 770-00xxx_shortdocs will occasionally see stylesheet (and other resource) tweaks. I am just wondering how that will complicate the file syncs.

Global project linking is really a one-way street. The files that are common to all projects would be stored in the Glb_project and should only be edited in the Glb_project. The files stored in the Glb_project are then imported into the child projects. When imported to the child project, the file/folder structure is the same as the Glb_project, and these files include a "lock" icon to indicate they are imported. Within the child project, if you attempt to edit an imported file, a warning dialog is displayed. If you proceed with making the edits anyway, the next time you reimport from the Glb_project, these changes are overwritten. So the work flow is to: 1) Make changes to global content in the Glb_project; 2) Launch the child project and import the modified content.

Within the child project, you can import content from the Glb_project in the following ways:
1) Manually by opening the import file and clicking the Reimport button.
2) Automatically by selecting the "Auto-reimport before "Generate Output" option in the import file.
3) Automatically by selecting the "Automatically get latest version..." option in the target file.

In all cases, the files to be reimported need to be writeable or the import will silently fail.
-If the project is bound to version control within Flare, Flare will automatically check these files out and overwrite them with the updated content.
-If the project is not bound to source control within Flare, you will need to make sure the files are locked/checked out (and thus writeable) prior to import. In addition, if ANY of the files to be imported are read-only, the import will also silently fail for all files. In this scenario, I would not recommend using the Auto import options unless the workflow includes locking/checking out all global import files prior to generating the output. I filed a bug about this last week.
-If the files to be reimported are not under version control at all, and always writeable, this shouldn't be an issue.

Thank you for the additional clarification Kellie. Really appreciated.

A few follow-up questions:

1) Are my steps for creating a master project sound?

2) When css (or other resources) tweaks are necessary in a child project (it won't be practical to edit the master), can I make the required changes and manually copy changed resources back to the master? At this point, I am not using source control (I'll cross that bridge a little later).

3) Since the master is not meant to be changed, I still require a master image folder where images are in a constant state of change. It appears that GPL is not suitable so shall I employ Flare's External Resources feature?

Thank you again... hopefully my questions/your answers will help others, as well.

[techwriter31]

A few follow-up questions:

1) Are my steps for creating a master project sound?

2) When css (or other resources) tweaks are necessary in a child project (it won't be practical to edit the master), can I make the required changes and manually copy changed resources back to the master? At this point, I am not using source control (I'll cross that bridge a little later).

3) Since the master is not meant to be changed, I still require a master image folder where images are in a constant state of change. It appears that GPL is not suitable so shall I employ Flare's External Resources feature?

Thank you again... hopefully my questions/your answers will help others, as well.

1) It's hard for me to say. I would recommend making copies of your projects and experimenting a bit. But to answer your questions:
You could certainly export the 770-00xxx_shortdocs and use this as the base for your global project. After doing this and renaming your folders to use the gbl_ naming convention, I would delete any files specific to the 770- project, that cannot be reused across multiple projects. Then, rather than deleting the 770- project, I would simply remove any of the content that was stored in the global project (stylesheets, page layouts, etc.) and rename the 770- folders to something specific to that project such as 770_Images, 770_Resources and 770_Topics. Then add your import file to the 770- project and import from the global project. When imported into the 770- project, you then have 6 folders in the Content Explorer; the three glb_folders from global, and the three 770_ folders in the child project.

2) Often, I will open the global and child project, make necessary changes in the global project, then reimport into the child project and test the changes. However, if the import is slow due to slow network connections, this might not be viable. You can certainly manually copy changed resources back to the master, but I would do so with caution.

3) The content in the global/master project can be changed. It just has to reimported to the child projects that will be used to generate the outputs. But maybe I'm misunderstanding the question?

[sdcinvan]

A few follow-up questions:

1) Are my steps for creating a master project sound?

2) When css (or other resources) tweaks are necessary in a child project (it won't be practical to edit the master), can I make the required changes and manually copy changed resources back to the master? At this point, I am not using source control (I'll cross that bridge a little later).

3) Since the master is not meant to be changed, I still require a master image folder where images are in a constant state of change. It appears that GPL is not suitable so shall I employ Flare's External Resources feature?

Thank you again... hopefully my questions/your answers will help others, as well.

1) It's hard for me to say. I would recommend making copies of your projects and experimenting a bit. But to answer your questions:
You could certainly export the 770-00xxx_shortdocs and use this as the base for your global project. After doing this and renaming your folders to use the gbl_ naming convention, I would delete any files specific to the 770- project, that cannot be reused across multiple projects. Then, rather than deleting the 770- project, I would simply remove any of the content that was stored in the global project (stylesheets, page layouts, etc.) and rename the 770- folders to something specific to that project such as 770_Images, 770_Resources and 770_Topics. Then add your import file to the 770- project and import from the global project. When imported into the 770- project, you then have 6 folders in the Content Explorer; the three glb_folders from global, and the three 770_ folders in the child project.

2) Often, I will open the global and child project, make necessary changes in the global project, then reimport into the child project and test the changes. However, if the import is slow due to slow network connections, this might not be viable. You can certainly manually copy changed resources back to the master, but I would do so with caution.

3) The content in the global/master project can be changed. It just has to reimported to the child projects that will be used to generate the outputs. But maybe I'm misunderstanding the question?

Thank you again, Kellie! Your answers are perfect.

[MacAller]

This has been a very helpful thread in terms of how to structure multiple projects and clearing up a lot of questions I had about global project linking. However, I have another wrinkle to introduce: what is the best way to store these projects in a version control system, such as TFS?

Specifically, would I create a folder to hold the global (master) project, and place the child projects in subfolders under that one? Or could I keep folders for the master and child projects all at the same level?