Global project linking - xref question

This forum is for all Flare issues not related to any of the other categories.
Post Reply
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Global project linking - xref question

Post by Psider »

Hi guys,

I'm hoping to clarify some advice about Global Project Linking (Flare Project Import). I've been reading the forums to understand the way people use this and the pros and cons for GPL and merging. I've found some conflicting advice about cross references, so I'm hoping @Dave Lee might jump in. :)

One post from 2016 says to use GPL when the projects are "tightly coupled" and you need to use xrefs, or want a lot of links between topics in both projects.
viewtopic.php?f=9&t=28227&p=123971&hili ... ts#p123971

Another post from 2018 says when using GPL you can't have cross references between, say, a topic in project 5 and a topic in project 7.
viewtopic.php?f=75&t=30045&p=130892&hil ... ng#p130892

Is it possible to use cross references between projects when using GPL?

For those working on multiple related projects, how do you manage the links between projects.

(A long time ago I used the merge functionality in Flare, and put manual relative links in snippets to minimise the pain of entering and updating them, but I want to find see if there are other options.)
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Global project linking - xref question

Post by NorthEast »

Psider wrote:Is it possible to use cross references between projects when using GPL?
No, not in any sensible way.

When you insert a cross-reference, you can only select a topic inside the same project.

For example, say I have a main project A, and use a project import (GPL) to import topics from two projects B and C.
- If I create a cross-reference in B or C, I can only select other topics in B or C. So I can't create a link from B to C, or B to A.*
- If I create a cross-reference in A, then I can select any topics from A, B or C - because the imported topics from B and C are all in the same project A.
- In project A, I can't edit imported topics from B or C without breaking their link, so I can't add/edit cross-references in those imported topics.

* Technically, I guess you can manually edit cross-references in B or C (before import), to point to topics that don't exist in the current project, but will come from the other projects after the import; but you probably want to avoid that path.


However, if your projects are "tightly coupled" and will have a lot of links between them, then my advice would be not to use separate projects. Combine them in a single project and produce several outputs from that. Flare's designed to do this.
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Post by Psider »

Thanks Dave.

I'm just trialling Flare at the moment, but I'm reluctant to combine the projects as, in the past, and again at some point going forward, multiple people will be working on the content, and I've only ever had bad experiences with multiple people working on the one project at the same time.

I'll have a play with merging, to see if there is a way to set up the source projects so browsing will create a relative path that matches the output (it might be possible if the Content folder is included in the output...we'll see.)

Edit: Never mind. The hyperlink functionality seems to hard code the absolute path.
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Post by Psider »

We interrupt this program for a mild moan.
<mild moan> Le sigh. I've yet to work on products that don't require links between modules and aren't worked on by multiple people and have the same release cycle.<end mild moan>
Now returning to your regularly scheduled program.

:P
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Global project linking - xref question

Post by NorthEast »

Psider wrote:I'm just trialling Flare at the moment, but I'm reluctant to combine the projects as, in the past, and again at some point going forward, multiple people will be working on the content, and I've only ever had bad experiences with multiple people working on the one project at the same time.
If you have multiple people working on the same content, then use source control.
That will prevent or help to control any conflicts.

Even if you work by yourself, like I do, I'd advise using use source control!

You'll have very bad experiences if you have multiple people accessing the same project, e.g. on a network share.
Using multiple projects doesn't actually prevent those problems either, unless you're going to physically restrict access to projects to certain people.
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Post by Psider »

Source Control is something I'm working on, but it's a slow process. At the moment, we are assigned a specific project. If we have a piece of work that needs a different project to be updated, we ask the relevant person to make the update. Every day or few (depending on how much work has been done on a project), and before weekends, holidays, etc, we create a zip backup on the network.

In a previous life we had issues with source control when working on the same project at the same time, with various hard-coded paths being saved, plus conflicts that were hard to figure out when the same topic was updated, and various behind the scenes things that mean even looking at a topic results in an "edit" and conflict that needs to be reviewed and resolved. I'm sure there were other things, but that's what I can remember off the top of my head. It was super annoying. Maybe these things have been improved in the intervening time.

(I'd ideally also like to be able to release the different modules independently, which I think would mean the merge option, rather than GPL. I'm still considering whether I need that for this product.)

(Oh, the other thing in my previous life, we tested branching so that the main branch could be released even if the child branch wasn't ready, but the merge tool was super confusing and didn't always get the tags right, so we had a lot of post merge work to fix everything up. Maybe source control merge tools have improved since then. I might post in Source Control and see how people handle it.)
peterb
Propeller Head
Posts: 25
Joined: Tue Mar 21, 2017 12:46 pm

Re: Global project linking - xref question

Post by peterb »

I was looking around through the forums for information on Flare backups for the purpose of past revision retention, and I happed upon this thread from earlier this year. If you or any other board readers may have some insights on the below, I would greatly appreciate information about your experiences.

-----
Our company has given us a hard NO on using our already-established source control platforms (Git and TFS), so we have no choice but to explore other means for retaining past revisions. It looks like your team is creating and zipping project backups once or more per week, depending on what is changing in the project. We are still migrating our initial content, but the final picture is going to be a Global Project Linking situation with a master project and something like six child projects, all of which will have content that is semi-regularly updated. I am wondering if your model would work for us, so if you are willing to entertain me, I have a few questions re: your experiences that I am interested in learning more about:
[*]How many Flare projects do you maintain, and about how frequently are you backing them up (on average)?
[*]Are you using Flare's built in Backup or Zip Project functions, or perhaps just copying/pasting the whole project to a backup folder, or another process I am not thinking of?
[*]Do you find that you are going back to review backed up content ever? If so, how easy is it to access/view this information?
[*]Do you feel that your process works well for you? What are some of the key points of your success with this? OR, if there are challenges, what practices could be changed in order to be more successful?

I appreciate you reading this, and your responses would definitely be a huge help to our team that is struggling with concepts on what to do in the absence of source control, so thank you very much in advance. Have a nice day!

PeterB
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Post by Psider »

This life, 4 projects (5 if you count the parent in the merge).

I'd recommend backing up at least weekly, assuming all your projects are worked on each week. Obviously if you only update one every few months, you'd only back it up when you update it. :) If you are making lots of significant changes to a project, then daily would be good - it depends how much work you want to red-do if your PC explodes. :P And I always do a backup immediately after releasing a production version of content.

I'm not actually using Flare, so I just zip using the Windows zip functionality. I'd recommend zipping, as it reduces file copy times and total file size. It's also a certain amount of protection so you don't accidentally modify your backup. (I think Flare allows some integration with the build process, so you might be able to write a script for, say, your production target, which automatically zips your source and copies to a network location using something like RoboCopy, or whatever tools you have access and support for. But that's hypothetical. Just throwing it out there as an idea.)

I'd say I access my most recent one or two backups a few times a year - sometimes I run a script and screw things up, or maybe I make a significant change that is then pulled from the product, and it's easier to get the old copy of a few topics from backup. I don't often go back to really old backups; one case might be to check when a particular change was made or if the content has always been that way, if an SME queries something.

This works reasonably in a small team. For larger teams I'd really recommend source control (does the organisation ban developers from source control? why is the documentation source any different from application source? for example.) You have to remember to back up this way, so a risk is you forget and you waste a heap of time when something is corrupted and you don't have a recent backup. Larger teams have more points of failure in this regard. Make sure you set up a standard naming convention and dedicated folders, so that everything is in a standard location with a standard name, so you can quickly and easily find the latest version. You might also like to have a slightly different name for your draft versions and your final production version, in case you need to go back to a previous production build. If there is a way to automate as much of this backup process as possible, I'd recommend it. For example, maybe you can get developers to write a script, so your team can just double-click on desktop icon and it automatically zips the project with the standard name and copies it to the network share.
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: Global project linking - xref question

Post by ChoccieMuffin »

I second Psider's suggestion that you find out what source control your devs use and "just" get them to create a separate area for you. Our devs use SVN, and it works fine for us too.
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
peterb
Propeller Head
Posts: 25
Joined: Tue Mar 21, 2017 12:46 pm

Re: Global project linking - xref question

Post by peterb »

I really appreciate these insights, so thank you. I have a three-person team that has good communication with each other, so I feel that this could be a workable plan for us. Perhaps we will gear up to fight the source control battle somewhere down the road. Thanks again!
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Post by Psider »

I should also clarify that in my current job I don't have to maintain multiple versions of the manual.

If you maintain patches (e.g 1.4, 2.1 and 3.0) then I would say you really need source control and branching. It makes life much easier.
peterb
Propeller Head
Posts: 25
Joined: Tue Mar 21, 2017 12:46 pm

Re: Global project linking - xref question

Post by peterb »

Thank you for that clarification. We really only have one live manual, and then a series of iterations of past revisions.

The only time we would run into some complexity is when we are maintaining a "not yet live" version of some bit of content, like when we are working on projects. For that, we may explore using conditions for the current and future versions of that content, and then do something like condition-switching in the output. I don't know; we haven't spent too much time thinking about this yet.
2bemused
Propeller Head
Posts: 10
Joined: Fri Aug 08, 2014 6:12 am
Location: Ireland
Contact:

Re: Global project linking - xref question

Post by 2bemused »

No matter what method you decide to use to backup your files, don't just assume that all is then fine. At some stage make sure that you can in fact restore files from the backup.
To do is to be - Socrates
Doooby doooby doo - Sinatra
Yabba Dabba Doo - Fred Flintstone
Post Reply