Global project linking - xref question

This forum is for all Flare issues not related to any of the other categories.

Global project linking - xref question

Postby Psider on Wed Apr 18, 2018 8:01 pm

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&hilit=merging+projects#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&hilit=global+project+linking#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.)
Psider
Sr. Propeller Head
 
Posts: 489
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Postby Dave Lee on Thu Apr 19, 2018 12:05 am

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.
Dave Lee
Master Propellus Maximus
 
Posts: 5414
Joined: Mon Mar 05, 2007 8:33 am
Location: UK

Re: Global project linking - xref question

Postby Psider on Thu Apr 19, 2018 1:22 am

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
Sr. Propeller Head
 
Posts: 489
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Postby Psider on Thu Apr 19, 2018 1:44 am

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
Psider
Sr. Propeller Head
 
Posts: 489
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Postby Dave Lee on Thu Apr 19, 2018 2:15 am

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.
Dave Lee
Master Propellus Maximus
 
Posts: 5414
Joined: Mon Mar 05, 2007 8:33 am
Location: UK

Re: Global project linking - xref question

Postby Psider on Thu Apr 19, 2018 5:33 pm

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.)
Psider
Sr. Propeller Head
 
Posts: 489
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Postby peterb on Wed Nov 14, 2018 10:03 am

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
peterb
Propeller Head
 
Posts: 10
Joined: Tue Mar 21, 2017 12:46 pm

Re: Global project linking - xref question

Postby Psider on Wed Nov 14, 2018 4:09 pm

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.
Psider
Sr. Propeller Head
 
Posts: 489
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Postby ChoccieMuffin on Thu Nov 15, 2018 2:46 am

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 2018.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
ChoccieMuffin
Propellus Maximus
 
Posts: 1872
Joined: Wed Apr 14, 2010 8:01 am

Re: Global project linking - xref question

Postby peterb on Thu Nov 15, 2018 9:06 am

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!
peterb
Propeller Head
 
Posts: 10
Joined: Tue Mar 21, 2017 12:46 pm

Re: Global project linking - xref question

Postby Psider on Thu Nov 15, 2018 10:54 pm

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.
Psider
Sr. Propeller Head
 
Posts: 489
Joined: Wed Jul 06, 2011 1:32 am

Re: Global project linking - xref question

Postby peterb on Tue Nov 20, 2018 1:55 pm

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.
peterb
Propeller Head
 
Posts: 10
Joined: Tue Mar 21, 2017 12:46 pm

Re: Global project linking - xref question

Postby 2bemused on Fri Nov 30, 2018 2:44 am

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
2bemused
Propeller Head
 
Posts: 10
Joined: Fri Aug 08, 2014 6:12 am
Location: Ireland


Return to Flare's General Discussion

Who is online

Users browsing this forum: No registered users and 5 guests