MadCap Software Forums

I am a member of a team of 3 writers who are using Flare with no source control tools. (For this discussion, assume that we are not able to get source control tools of any kind.) We need to be able to all contribute to the same Flare project. We are looking for best practices--both for developing new topics and updating existing topics--for managing multiples authors. We realize that for new development, we can each author separately in projects on our PCs and feed into a respository project, but we are concerned about creating a final production phase where we would need to resolve/create cross-references, etc. since we do not typically have time at the end of a deliverable. Plus, we would still need a strategy for updating existing topics. We also need to be able to work in projects on our PCs rather than on a shared network.

I realize that this is a broad question, but if there were any way to get detailed advice about how to approach this problem, it would be appreciated.

My first thought is to use global project linking, to "sync" everyones files together at various times throughout the development. You could set up a condition called "Changed" and each time someone changes a file they tag the topic or image with that conditon. Then you can import based on just that condtion. Ideally you'd use a network sharing to import the files, but I guess it would also work if you zipped up projects and extracted them to a common location on your PC.

You'd have to ensure no-one is working on the same files at once. Perhaps divy up files into folders, and make sure only one person is ever working on files in folder at any one time. Another challenge would be how to make edits to common files like the TOC, glossary and stylesheet. Maybe make one person responsible for these files?

I would add that you should include making a backup of the existing files prior to working on them a part of the workflow for all writers. That way if something does screw up you can revert back with at worst one day's work lost (which is not good by any means, but it beats losing everything....)

What I would do is designate one TW as Flare Guru who mainly does the work in Flare, but not so much of the content creation. The other two exclusively craft the content (screen shots, videos, animations, etc.). That way you don't have contingency issues or one TW undoing the work of the other TWs by accident. Typically, you get more consistence this way as well. If you agree on a style guide you can switch roles throughout the project, for example when a TW is better equipped / more skilled for writing a particular section. That way you have only one TW working on the project while the others use Flare to generate the topics (which can be copied into the 'real' project). If you have flextime use it to your advantage and maybe mix things up a bit more. Some people have the gift of being good indexers, while others struggle with it (like myself, I tend to add too much stuff).
I discourage to make it so that all TW work on the same project files at any given time. While that may be possible to some extent it just adds a source for problems.

That said, take a look at SVN (or CVS) in combination with the PuskOK plugin. The plugin costs 29$ per seat and SVN / CVS are freebies. If I'd be in your position and the company doesn't have 100 bucks to spare I'd pay that out of my own pocket just for the sake of being able to do real work. In the grand scheme of things, for a company that can keep three TWs busy the few bucks for the tools you guys need should be nothing more than peanuts. But, what do I know, maybe you three TWs ARE the company.

We are 2 TW:s working with documentation at my company, and we used TFS 2010 before for our doc check-ins. But with TFS we could not use the global project linking. So now I am testing global project linking with our projects on a file server without any source control. It works really fine in Flare 7, even though the network performance is slow. To improve the performance, how can I in the easiest way work in Flare locally and "check in" the files to the file server without using TFS? Thanks in advance.

heal wrote:But with TFS we could not use the global project linking.

I have linked projects in TFS; what aspect doesn't work for you?

Dave Lee: Global linking works fine now using Flare 7.1 and 7.1. We had to change the structure in TFS to make it work.

Hi Dave and heal,

Could you please elaborate a bit on that?
I'm new to Flare and have set up Flare (version 7.2) in conjunction with TFS.

But now I'm figuring out how to link my separate Flare projects to a global Flare project that contains all resources and shared content for these projects. All of them are stored in TFS.
In the Project Import Editor the only option I see is to link the source project by a (UNC) file path and not by a TFS reference.

How should I set this up to get this scenario working?

NetDisplaySystems wrote:In the Project Import Editor the only option I see is to link the source project by a (UNC) file path and not by a TFS reference.

How should I set this up to get this scenario working?

Yeah, that's a limitation with project imports; the project path needs to be the same on each person's PC.

Hi Dave,

Thank you for your quick reply.

Having the same (TFS) project path on everyone's PC could be a little tricky, as we do have the same folder structure, but not the same drive allocation (some put it on C:\, some on D:\).
I guess I was hoping Flare would offer the possibility to traverse TFS further down to locate the global source project as you already specified the exact TFS location in the Source Control Provider.

So, no way to do that, then?

Hi NetDisplaySystems, you can have a so called workspace on your computer that reflects the structure in TFS. Use relative links in the Flare import file as follows:
Important! To use project linking, the structure of your documentation also have to map the structure of your source project in TFS so that they are on the same level in the "tree". In this example the source project is called Shared.

Hi heal,

Thanks a million!
That was really helpful!
I think I've got it to work now.
The link graph is showing in the document's icon, so I guess it should work now.
I'll being do some tests to be sure, though.
Once again, thank you very much!

Hmmm, I find this a bit confusing.
I've linked some files via a global project.
Initially, this is correctly indicated by the link image in the file icons.
When I run a Build or do a Re-Import these change back to the icons used with source control (TFS), showing a lock or red check image.
I suspect (but am not sure) the link is still there, but the link image in the icons never returns...

Is this behavior intended or am I doing something wrong?

Flare is not so clever. It wants to add and check out imported files because it adds a local copy of the imported files in your workspace. You will only need to check in the project file together with the Content and Project folders to TFS. Make sure that you have not checked your "global files" by mistake from the source project to your documentation project on the TFS server. If they are, delete them. Examples of unnecessary folders to check in are the Users (under Project) and Output folder.

LOL!
Yeah, it seems Flare's handling is not that logical or intuitive as I would have hoped.
I've played some more with these settings and if I understand you and Flare correctly, the best way is to initially import the global files, check them in: now they're linked.
Whenever there's a change (verify with the Re-Import window), you don't Re-Import, but delete the linked file and re-link without adding the file to Source Control.
A little cumbersome, I think...

I'm not really sure I follow what you're doing; I find importing is pretty straightforward, and don't need to delete anything when I re-import.

After starting the re-import, Flare prompts me to confirm the files to import. When I accept the import, it will copy the updated files to my project (overwriting the old versions) and leave them checked-out. It will also leave the updated Flare import file checked-out. I don't need to delete any files.

heal wrote:Examples of unnecessary folders to check in are the Users (under Project) and Output folder.

I'm guessing you added the project files using TFS rather than Flare? If you bind your projects from Flare, these folders will not be included in TFS.

Hi Dave,

Maybe it's because I'm quite new to all this, but I've noticed that at times the files I want to link to are (forcefully) copied and placed into TFS, while I just want it to be a real links.
Perhaps it's my idea about files being linked or maybe I'm doing something wrong at re-importing.
I will look into it some more later on, lacking time at the moment, but for now this works.

Thank you both for your assistance!

NetDisplaySystems wrote:Maybe it's because I'm quite new to all this, but I've noticed that at times the files I want to link to are (forcefully) copied and placed into TFS, while I just want it to be a real links.

Just to be clear - a project import will make copies of the imported files in your project, they aren't just links to files in the other project. So after running a project import, the new files in your project will be added to TFS.