Advice on structure of a Flare project

[rogersm]

Hi all,

In advance, I hope I am posting in the correct forum and apologies for the long winded question from a newbie evaluating Flare.
Our company is evaluating a move from our current unstructured Framemaker authoring environment to Flare. At the moment, we are just trying out a trial version of Flare and so far we very impressed with its potential. One of our main drivers for comtemplating a move away from Framemaker is the issue of reusing and managing similar content between products. The image attached is a basic representation of our document structure in Framemaker:
[*] Product A (our main product) has a number of guides (framemaker books). There are approximately 27 guides in it and some of these are between 300 and 400 pages long.
[*] Some of the content in some of Product A's guides is similar (but not exactly the same) to the content in Product Bs and Cs Guides. For example, when I say that the content is not exactly the same, I mean that Product A could have a procedure with 12 steps, Product B could have almost the same procedure but with 2 less steps and different screenshots, Product C could have 4 more steps and different screenshots, and each Product has a different name in the procedure text.
[*] The Products also have guides that are exactly the same
[*] The output for Product A (and potentially other products) is one pdf per guide and 3 separate html documentation sets (as outlined in the attachment). We use WebWorks to generate the HTML from our frame files.
[*] The guides in Product A include cross references between them (that is, there are cross references between the Framemaker books)

The unstructured Framemaker solution to having similar content reuse is to use text insets with variables and conditional text for each Product. But we think that this will be very difficult to maintain. This is one reason for us to consider Flare.

Maybe this is a difficult question (or impossible!), but if we were to move to Flare, how would you recommend us to organise our document strucure? From my very limited read on Flare it seems that we could maybe go down one of the following routes:
[*] Have one Flare project with all our guides and use Flare topics, snippets, variables, and conditions to reuse our content. With this approach, maybe each of our guides would be a target? And perhaps we would need a table of contents per target? This approach would result in a large amount of topics and it seems like it may be difficult for managing what content is shared and tracking all of our conditions and variables?
[*] Have a Flare project per guide and one global project. The global project would contain all our reusable content and we would import this content into the individual projects (using global project linking). I presume there when importing into the individual projects, we can specify variables and conditions to account for differences between the content? This approach seems easier to manage perhaps, but I am not sure if the html documentation sets could still be produced or if we would lose the cross references between our current framemaker books.

Overall, I guess my questions come down to whether Flare is a better tool for handling our situation of sharing similar (but not exactly the same) content between guides, and whether we can still merge our guides into HTML documentations sets.

Sorry about the newbie questions and maybe I need to read up more on the capabilities of Flare, but the trial period will be running out relatively soon so I thought I would try and ask some questions here.

Thanks for any help,
mark

[ChoccieMuffin]

Hi, and welcome to the forums. You'll find them a really useful resource with some very helpful contributors.

Your summary is very clear. In your circumstance I would opt for Global Product Linking, as you described. Have a global project which contains common content and use conditions to mark the differences between the products. It's a very powerful feature and once you get your head around it you'll be amazed. I suggest you also use a variable for the product name, so that when you use a topic in one of the child projects the variable displays the correct name, rather than having to use conditions for that aspect.

This thread might be helpful. http://forums.madcapsoftware.com/viewto ... 75&t=19787

[rogersm]

Hi ChoccieMuffin,

Thanks very much for that, quite a detailed link. So if Global Project Linking is an option, would the following be a reasonable approach?

We could potentially create 5 Flare projects to handle our document structure and output delivery as follows (see attached):
[*]1*Flare Project Content - This could contain all of our topics from all of our Framemaker books. This would be a substantially sized project in terms of the number of topics. Would you organise the topics by creating appropriate folders in the Content Explorer?
Alternatively, instead of this one project, would it be better to have individual Flare projects per Framemaker book?
[*]1*Flare Project Master - This could contain all of the variables, css, cover pages, conditions,... I guess we use Global Project Linking to import this content into the other two projects.
[*]3*Flare Project Outputs - Each of these projects is used to consolidate topics from the Flare Project Content and deliver the output. I guess we use Global Project Linking to import this content and apply appropriate conditions and variables to handle topic content that is similar (but slightly different) in each of the project outputs.
If you use Global Project Linking to import a topic from a "source" project to a "destination" project, can the "destination" project edit the project topic? If so, does that break the link between them.

Thanks again for any help, much appreciated.
mark

[ChoccieMuffin]

Just looking at your diagram (they do say every picture paints a thousand words!) makes your situation very clear.

In your situation I would have the following setup:

(1) A Globals project for things that are truly global (stylesheets, master pages, page layouts, common topics like company address, cover page etc, common conditions, common snippets - basically anything that is likely to be used in every, or almost every, project.
(2) Four separate Flare projects to contain your imported FrameMaker files. This makes it easier to condition stuff for import into the output projects. It could just get too complicated if they all went into a single project.
Question - are you intending keeping the links with FrameMaker or just import once and from then manage everything in Flare?
Depending on what your stuff is, you might find more logical ways to separate the content so that you don't end up with too many projects containing multiple conditions. For example, it looks your C1 project could output Output 2, so you would only need the four oval projects and two of the square projects, not three.
Question - Is there any sensible logic to the FrameMaker books? If you were to bring them all into Flare would there be a more sensible way to organise them, for example in modules? That might be something to consider if you're going to dump the link to Frame but probably not worth the hassle if you're keeping it.

To answer your question, if you need to edit a topic, do it in the source project, i.e. your oval projects. I know it's called "global project LINKING" but in truth it's "global project IMPORTING".

Others may have other suggestions, and of course you know your material better than I do so my suggestions might be silly.

[NorthEast]

Looking at your proposed structure, I definitely wouldn't advise having the 3 separate 'Flare Project Output' projects, which import from the 'content' project.
It looks like they're just used to import subsets of files from the larger project, so that you can build a separate target/output from each. However, that's just adding an extra layer of unnecessary complexity, since you can build all these separate outputs directly from the large 'content' project.
If everything is going in the large 'content' project, then you could just set up separate targets within that project to produce each of the outputs required. You can control what is included in each target/output by using conditions.

The idea of the 'flare project master' is sound - I use a 'master' project for the same purpose, which contains stylesheets, page layouts, etc. All of my projects are linked to this 'master' project, so any changes to the master can easily be rolled-out.

I've worked on a similar project, where I had to import content from several FM books; where the purpose was to combine them into a single large project.

The big question here is whether you plan to continually update content in FM, and re-import that into Flare; or whether it's a one-way process, and you're ditching the FM files afterwards.

* If you plan to maintain content in FM and re-import, then frankly I don't envy that workflow. You will need to be very disciplined in how you use FM, to ensure that you get a 'clean' import into Flare.

* If it is a one-way import, then you don't need run all the the FM imports in a single large 'content' project. It may be easier to import them as individual projects, tidy them up, then just copy the topics from each into the large 'content' project when you're happy.

Either way, to start with, I'd suggest importing the product FM books as separate projects, at least until you are confident with the import process. You might only find out that an import hasn't worked as expected long after the event.

[ChoccieMuffin]

Looking back at your first post where you say you have different products, I would avoid having just one big pot for your source topics as Dave suggests, as that could end up being a condition tag nightmare.

It looks like you have modules which are used slightly differently between the different products, so I would have a Flare project for each module, with conditions applied to say whether it's Prod A only, Prod B only etc.

Sounds like you've got a fairly networked bunch of stuff, but with careful thought it can be managed effectively. Best of luck.

[rogersm]

Hi all,

Thanks very much for all your replies.

To follow up on your questions:
[*] Our goal would be to eventually manage everything in Flare, however during the migration period from Framemaker to Flare I think we would have to maintain links with Framemaker for a certain period of time.
[*] I am not sure if modules has a specific meaning in the context of Flare? But I guess you are suggesting the possibility of organising the content in a more logical structure in Flare. And yes, this is something we need ti consider. At the moment, we are still thinking in terms of content structured in Framemaker books and just transferring these books to Flare projects. But perhaps the move to Flare is an opportunity to improve our organisation of the content.

You have both given me lots to think about so thanks again.
Just one last question, Dave mentioned copying topics between projects, is this an easy thing to do or are there multiple considerations?

thanks again,
mark

[NorthEast]

Looking back at your first post where you say you have different products, I would avoid having just one big pot for your source topics as Dave suggests, as that could end up being a condition tag nightmare.

What do you suggest instead?

As described, the content appears to come from different FM projects/books, e.g. A, B, C.

However, there isn't a one-to-one correlation between the FM inputs and the required outputs. The outputs are a mixture of content from A, B, and C; e.g. output 1 has parts of A and C, and output 3 has parts of A and B.

Therefore, the project that you build these outputs from must contain all this content from A,B,C that's required in the outputs - and you would have to use conditions to select which content is included in each target/output.

As I mentioned though, I would get the FM import process working first, before combining the content in a large project.

[ChoccieMuffin]

Dave, to answer your question I would aim have a one-to-one import from a Frame book to a Flare project to start with, particularly as our friend here is likely to keep the link with Frame for a while. Ultimately it would be better to structure Flare differently, as described below. The reason I wouldn't want just one big pot of topics from all the imports is that if you generate outputs from that big pot you run the risk of having a help file contain topics that are completely irrelevant to your output but which appear in the search, unless you ensure that all topics appear in the TOC and you remember to set the right options on the target (Advanced tab, I think). Alternatively it could make it much more complicated and troublesome to tag topics for importing into new Product projects (the square ones in the original diagram).

And no, I was only using the term "module" generally, as it looks like your products might be modular (as in, Company offering = drinks dispensing system within which Product A = Teasmade with red buttons and Cappuccino machine, Product B = Teasmade with blue buttons and cold drinks dispenser, Product C = Cappuccino machine and cold drinks dispenser, Product D = cold drinks dispenser only, Product E = Teasmade without any buttons, etc) so the different modules (types of drink) are used in different products. Eventually I would aim to have a set of Flare source projects (your oval projects) that would contain the modules, so you'd have a Teasmade Flare project that contains all the text (red buttons, blue buttons and no buttons) and you would use condition tags and import filters to import the relevant topics into Products A and B, and perhaps use the Teasmade project to generate Product E seing as it doesn't need any other modules.

Does that make sense? (Not that I imagine you're working on a drinks dispensing system but it's a useful imaginary product offering when talking about this kind of thing. I quite fancy Product A myself...)

[NorthEast]

Dave, to answer your question I would aim have a one-to-one import from a Frame book to a Flare project to start with, particularly as our friend here is likely to keep the link with Frame for a while. Ultimately it would be better to structure Flare differently, as described below. The reason I wouldn't want just one big pot of topics from all the imports is that if you generate outputs from that big pot you run the risk of having a help file contain topics that are completely irrelevant to your output but which appear in the search, unless you ensure that all topics appear in the TOC and you remember to set the right options on the target (Advanced tab, I think). Alternatively it could make it much more complicated and troublesome to tag topics for importing into new Product projects (the square ones in the original diagram).

Either way, both approaches will require exactly the same level of complexity in terms of conditions. If you have a single project with multiple targets, you'll need to use conditions to control what is included in each target output. In your suggestion, where you're setting up a separate project for each target/output, you need the same degree of conditions to control what files are imported into each project.

Flare is designed for single sourcing and can handle producing multiple outputs from a project, and I've used a single project approach in similar scenarios without issues. If anything, I would think that splitting it all up into several smaller projects for each output would just add more complexity.

I agree about the initial FM import - as I said, I would initially set these up as separate projects until they are working the way you want, before adding them all into a large project.

[ChoccieMuffin]

Good point, Dave.

The approach I describe works well where I am, as it means that both myself and my colleague can be working on separate modules, knowing that what we're doing isn't going to end up overwriting what the other one is doing (we use SVN but not linked into Flare). I can see some of the advantages of using your method though.

rogersm, ultimately you will be the one to choose the approach that suits you and how your company works. Both Dave's approach and mine have advantages.

Keep asking Flare questions on here, there's bound to be at least one person who knows the answer!

[rogersm]

Hi all,

Thanks again for both of your replies and advice. It is a great to have an active forum for this.

If we take one approach in Flare, is it a large job if we decide to try an alternative approach? For example, if we take the approach of the one large project with all of our content, is it a significant job if we then decide to move to a project per Framemaker book? I guess it would depend on the amount of content we have perhaps.

thanks,
mark

[Nita Beck]

If we take one approach in Flare, is it a large job if we decide to try an alternative approach? For example, if we take the approach of the one large project with all of our content, is it a significant job if we then decide to move to a project per Framemaker book? I guess it would depend on the amount of content we have perhaps.

If you take the one large project approach, yes you can easily break it up into smaller projects by using Flare 10's Export Project feature (found on the Project ribbon). You can elect to export by target, condition, or file tags, or to select specific files to export. You'll end up with a new Flare project with only the exported files.

FWIW, I agree with Dave's project structure approach, that is, to ultimately have a large project that supports the multiple products. I think it'll be much easier to maintain a large project that supports multiple products for which there is a significant number of shared files than it will be to maintain multiple smaller projects that require lots of importing and re-importing.