Limit on Number of Outputs in Single Project?

[techwriter31]

Is there a recommended limit for the number of outputs that we produce from a single project? I'm in the process of porting our existing documentation from FrameMaker to Flare and need to determine how many projects to create. Ideally, we want to make changes in a single location, so we're leaning towards porting all documents to a single Flare project (plus, project/TOC linking won't work for us since the output is PDF). If we do this, we'll be outputting 14 different targets.

Also, are there any known issues with having multiple languages in a single project? For our quick start guides, we create PDF booklets with up to 9 languages. If possible, we'll need to include all languages in the same project for these documents.

[RamonS]

My recommendation is to make one project for each product documented. The only time I'd differ from that is when there is really a lot of content that can be shared. The reason is that otherwise you have to work with many conditions and that gets confusing really fast. If the content for each output is entirely different then there is no reason to throw that all into one project.
In regards to languages, if you have two or three languages it may be OK to handle that in one project with conditions. I'd split it into individual projects if there are more languages. Exception here is when each language content could be covered in one or two topics and the chance of adding more languages is not that great. That might work out for your quick start guide.
I think there are no technical limits that you would encounter, but it is more of a manageability issue when dealing with diverse content and many conditions. If you split it into different projects you will never run into the situation where one output contains things it shouldn't.
It all depends on size, how much can be shared, how much has to be tied together, how many languages, and how well you can stay organized. There is no hard rule and a lot has to do with personal preference as well.

[techwriter31]

Thanks! A lot of the content does contain overlapping information. For these scenarios, I'm hoping to reduce the number of overall topics and use variables for the different product names. In addition, we have a few manuals that describe the installation of several of our products together (for example, we have separate installation manuals for the individual products, and other manuals for products that are sold as bundles and connected to one another). I think that due to these manuals, we'll have to keep them all in one project...I guess I'll have to try it out and see how it goes.

[techwriter31]

Or would it make more sense to have a single "parent" project with several smaller "child" projects and using the global project linking feature? I'm testing it out now, so I'm not sure what the limitations might be, but it seems like it could be a good solution.

[RamonS]

That could be a solution. I haven't tried it myself, so I am hesitant to endorse it.

[Nita Beck]

Or would it make more sense to have a single "parent" project with several smaller "child" projects and using the global project linking feature? I'm testing it out now, so I'm not sure what the limitations might be, but it seems like it could be a good solution.

With no hesitation, let me say "Yes, use Global Project Linking!" I've been using GPL for several of my clients' work. In my global project, I've got stylesheets, page layouts, master pages, snippets (for boilerplate language such as their publication notice), variable sets, conditional sets, file tag sets, images, and even whole topics (such as a topic on how and when customer technical support can be reached), which appear in every single one of the clients' publications.

For each product, I have a local project that contains only items that are unique to that product.

I have found it helpful to set up a folder structure in the Content Explorer that clearly lets me distinguish between my global content and my local content. Back in the global project, I've got three folders: GlobalImages, GlobalResources, and GlobalTopics. The first time stuff is imported from the global project, Flare adds these three folders to the local project, so I end up with:

GlobalImages
GlobalResources
GlobalTopics
Images
Resources
Topics

I can easily see where stuff is.

[techwriter31]

Thanks! This makes me feel slightly more confident about trying it out.

I need to figure out the best strategy for our documentation.
- We'll be outputting about 15 different printed documents (3/4 of them are installation manuals and about 1/4 are QSGs).
- For each printed manual, we'll also be creating a webhelp version for posting to our support site, for a total of ~25 outputs. The webhelp versions will be identical to the PDF content, minus the front & back covers, Table of Contents, etc., so I'm not too worried about these.
- We have 4 technical writers who may be contributing to the content at different times.
- The content will be translated into 6 - 8 languages, depending on the project.
- We use Rational ClearCase source control to check in/out all of our documentation.
- We have several different hardware product "families". Each product family contains some similar/overlapping content.
- Depending on the document, we may explain how to install one product independently, or how to install several of our products to work together (several product families in the same document).
- We also have several existing Flare projects that contain software documentation for our hardware projects. At some point, we'd like to be able to pull some of this documentation into our existing hardware manuals to make a combined "user's guide" that walks the user through hardware installation and how to use the software.

I'm trying to figure the best way to structure the project(s). It sounds like the options are:
1) A single project that contains all content and a lot of conditional markers, but offers the most flexibility as long as it's managed properly.
2) A single parent project for all shared files (for me, that'd be the stylesheet, page layouts, our legal notices/copyrights topic, variable sets, condition sets, and possibly snippets), and a separate child project for each product family. I could use variables and conditional text in each child project to output the individual (single product) installation manuals and use project linking to create the more complex multi-family projects.
3) A single parent project for all shared files and a separate child project for each product/output. It seems like this route would be the easiest from a conditional tagging standpoint because it’d be less confusing, but also seems to be the most restrictive.

Can you recommend any resources on global project linking in Flare? I've just started looking for information online, but haven't found much. Any thoughts or advice would be greatly appreciated!

[Nita Beck]

I'm jealous! Your project sounds terrific!

Can you recommend any resources on global project linking in Flare? I've just started looking for information online, but haven't found much.

I don't really know of any third-party resources that cover GPL in any depth (if at all). Sorry..

Regarding your options, I wouldn't go with the first at all (the single mega project with everything in it), especially considering that there will be a team of writers working on the documentation. I think you'd quickly regret that approach.

[techwriter31]

Thanks! I have a few more questions...

1) For now, I think I’m going to use option 2, with a single parent project and a separate child project for each product family (see graphic below). Using this method, I could create the “Global” directories for the shared parent files. But, if I share files between the child projects (for the manuals that contain several product families), would you recommend also storing these child-to-child shared files in the “Global” directories?

global.gif

2) When reimporting files, does Flare care whether the shared file is read-only? For example, since we use source control it's more than likely that we would check out the shared file, make changes and check it back into ClearCase. Once checked in, the file is read-only.

[sdcinvan]

Thanks! This makes me feel slightly more confident about trying it out.

I need to figure out the best strategy for our documentation.
- We'll be outputting about 15 different printed documents (3/4 of them are installation manuals and about 1/4 are QSGs).
- For each printed manual, we'll also be creating a webhelp version for posting to our support site, for a total of ~25 outputs. The webhelp versions will be identical to the PDF content, minus the front & back covers, Table of Contents, etc., so I'm not too worried about these.
- We have 4 technical writers who may be contributing to the content at different times.
- The content will be translated into 6 - 8 languages, depending on the project.
- We use Rational ClearCase source control to check in/out all of our documentation.
- We have several different hardware product "families". Each product family contains some similar/overlapping content.
- Depending on the document, we may explain how to install one product independently, or how to install several of our products to work together (several product families in the same document).
- We also have several existing Flare projects that contain software documentation for our hardware projects. At some point, we'd like to be able to pull some of this documentation into our existing hardware manuals to make a combined "user's guide" that walks the user through hardware installation and how to use the software.

I'm trying to figure the best way to structure the project(s). It sounds like the options are:
1) A single project that contains all content and a lot of conditional markers, but offers the most flexibility as long as it's managed properly.
2) A single parent project for all shared files (for me, that'd be the stylesheet, page layouts, our legal notices/copyrights topic, variable sets, condition sets, and possibly snippets), and a separate child project for each product family. I could use variables and conditional text in each child project to output the individual (single product) installation manuals and use project linking to create the more complex multi-family projects.
3) A single parent project for all shared files and a separate child project for each product/output. It seems like this route would be the easiest from a conditional tagging standpoint because it’d be less confusing, but also seems to be the most restrictive.

Can you recommend any resources on global project linking in Flare? I've just started looking for information online, but haven't found much. Any thoughts or advice would be greatly appreciated!

Wow, this is absolutely fantastic Kellie! Your requirements are very similar to my own.

This thread is my 'Rosetta Stone'... finally cluing me in about how GPL linking works and in a manner that is relevant to me.

Thank you to all the contributors in this thread!

Kellie, you wrote this four years ago. Are you still involved with this project? How is/was your experience with accomplishing these goals in Flare?

Thank you.

[techwriter31]

Hi sdcinvan! I'm glad this post has been helpful. I love the global project linking feature, because it has greatly reduced the duplication effort and human error on my part!

I am still involved with these projects - funny timing too, as I'm in the process of streamlining our existing GPL implementation to reduce the ramp-up time for new writers and reduce the maintenance workload for me. I apologize if this is a bit rambling, but here are the methods we're now using.

- We have a single "Global" English project that stores all of the shared content that will not be edited (images, stylesheets, page layouts, master pages, table styles, snippets, conditions, reports, Legal Notices, etc.). We have a companion "Template" English project that stores files that will require editing within the new child project (target files, skins, an import file, etc.). The template files are already configured to use all of the settings that we need. The template project does not contain any Global files. When creating a new project, the workflow is to create a new project based on the template and then import content from the Global project. Both the Global and Template projects are available from a network location, so all writers can point to the same source location.

- We create a new Flare project for each larger product line. (Initially, I had thoughts of using GPL between child projects based on conditions. I abandoned this, as it was overly complex.)

- Per Nita's recommendation - 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.

- We have one "Global" English stylesheet in the global project, with mediums defined for all outputs. We define the Master Stylesheet in the target file.

- We also have a different "Global_xx" stylesheet for each language that we translate to, but we reference the English stylesheet as an import and only include translated auto-text and language-specific features in these stylesheets. Then, when we translate these projects, the vendor just specifies the translated stylesheet as the Master Stylesheet in the target, and all of our autotext is already translated and included in the output. The translated stylesheets are stored in the English Global project and imported into each child project.

- We use "Global" and "Local" snippets. 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 use "Global" and "Local" conditions: We have a small set of "Global" conditions, such as "Hidden", "Image", "Print_Only", "Mobile_Only", etc. Then, within each child project, we have a "Local" set of conditions that are specific to the outputs being produced. (I previously had a monolithic set of conditions in the Global project to allow child-to-child GPL, but this too became cumbersome to maintain...and renaming conditions a nightmare. MUCH happier with how it's set up now.)

- All images in the Global project contain no text (i.e., no translations required), and are typically regulatory images or images used for our skin files.

- Not specific to GPL, but...we previously had different page layouts for front covers, body and back covers. Now, we have a single page layout for each of our PDF outputs. Each page layout contains three page types for the front cover, normal (body/chapter pages) and back cover. We then use the outline TOC to define the chapter breaks, and when necessary, page breaks. We specify the Master Page Layout in the Target file and the "auto-inject" blank page option deselected. This configuration has greatly simplified our process, as we no longer have to specify the page layout to use in each TOC node. Also, we use the default page numbering and allow it to start on the front cover, so the PDF page numbering and actual page numbering are the same.

Hope this helps!

[aneedell]

Hello, Kellie.
Thanks so much for posting this information. It is immensely helpful! I have a question about your Flare Project Import Files: do you include the .flimpfl file in your template project? And, do you have a single .flimpfl file, or multiple such files? Thank you,
albert

[techwriter31]

Hello, Kellie.
Thanks so much for posting this information. It is immensely helpful! I have a question about your Flare Project Import Files: do you include the .flimpfl file in your template project? And, do you have a single .flimpfl file, or multiple such files? Thank you,
albert

Good question! Yes, we do store a Global.flimpl file in our template project, and we only have a single .flimpl file.

[aneedell]

Thanks for your reply, Kellie. If I may, I have one other question. It seems that to create a Flare Project Import File in a template project, you need to first create it and then carefully refrain from executing it (we would want only the projects created from the template project to execute the import file). Is there a way to create the import file as a true template, such that you cannot accidentally execute it? Thanks again!
albert

[techwriter31]

Is there a way to create the import file as a true template, such that you cannot accidentally execute it?

Sorry for the delayed response! Not sure if this helps, but we store our global and template projects in version control (but they are not bound to Flare) and these projects are mirrored to a network location. When creating a new project based on the template project, the writer points to the mirrored network location and once the new project is created, the template Global.flimpl file points to the mirrored global project location. I maintain the global and template projects and am typically the only writer making changes to them. There is still a chance that the import file could be accidentally executed, but since in version control, the import file is read-only and would have to be locked/made writeable prior to an import, and then I'd have to manually add/commit the imported files.

[aneedell]

Thanks once again, Kellie. Good answer: it certainly does help. We use Perforce version control, so we have the means to revert. I find Flare's Global Project Linking to be absolutely essential but not very elegant in its design. Your replies have helped me understand it better and have confirmed that the approach we are taking is correct. Thank you!

[MaryseCoutureSh]

Hi Kellie,

Your post is very helpful for me, too. It will help me to organize my global and child projects. Thanks a lot! I have a question: do your global/child projects have different CSH files (alias and header files)? If yes, how you manage these files?

Thanks,
Maryse

[techwriter31]

I have a question: do your global/child projects have different CSH files (alias and header files)? If yes, how you manage these files?

We don't maintain global CSH files. For the projects that use them, they are maintained in the local/child project only.