Managing source/version control? How're you doing it?

[pvz]

I'm looking for some collective wisdom from the users of Flare.

How are you managing source and version control for your help projects?

We had hoped to use the built-in Flare-TFS integration but it's not going to work for us due to our multiple code branches and a need for multiple TFS workspaces. So, I'm looking for ways to change our processes instead.

We're a shop of 3 technical writers working on a single large Help system (we're generating webhelp, but that's beside the point I think). At present we all work in all areas of the help project. To get around collisions, one of us checks out our source from TFS and works in it locally. If the other writers need to make changes while the help source is checked out, they do so in a (manually created) copy and wait until the system is checked back in, at which point they check it out and fold in their changes. It's clunky but has worked for a year now. Before that I was the only writer, so I didn't have to coordinate anything with anyone! :>

I'd love to hear how other similarly organized writing groups are handling source and version control.

One note: We may be unusual in this, but we are also checking our output into TFS. Not sure this matters except that it has contributed to our issues with Flare-TFS integration because our output lives in an entirely different folder than our help source. We do this because our built product is stored in TFS and our help system is just one directory in that built product.

thanks in advance for any replies.

paul van zwalenburg
technical writer
daptiv, inc

[SteveS]

One note: We may be unusual in this, but we are also checking our output into TFS. Not sure this matters except that it has contributed to our issues with Flare-TFS integration because our output lives in an entirely different folder than our help source. We do this because our built product is stored in TFS and our help system is just one directory in that built product.

If it helps you can keep your output out of source control. In fact, some consider you should keep anything that can be recreated doesn't need to be kept in source control. We don't keep executables, dlls, etc in source. We don't keep my printed doc, webhelp, or chms either.

[forfear]

There are some really good posts and discussions that relate to this here..

http://forums.madcapsoftware.com/viewto ... ce+control

[KevinDAmery]

One note: We may be unusual in this, but we are also checking our output into TFS. Not sure this matters except that it has contributed to our issues with Flare-TFS integration because our output lives in an entirely different folder than our help source. We do this because our built product is stored in TFS and our help system is just one directory in that built product.

If it helps you can keep your output out of source control. In fact, some consider you should keep anything that can be recreated doesn't need to be kept in source control. We don't keep executables, dlls, etc in source. We don't keep my printed doc, webhelp, or chms either.

I don't put any of the output folders in source control, but I do add the completed help to source control--not so I can recover it, but so that my developers can consistently get the latest help file when they do a build (we're not set up to have them run Flare from command line).

[forfear]

We use source control to source code only. We try not to put the binaries or compiled help in the source control server. I think the location for this compiled help is usually called the QA drop server. Usually just a file server where developers and everyone else dumps their latest compiled versions of source code (dlls,exe, bins) in, for the release engineer to package it in to a release.

[Andrew]

I'm not sure if I'm alone in this, but our team (4 of us) doesn't bother with source control at all. We've had very bad experiences with RoboSource Control (which was required for multi-author in RoboHelp), and don't really have the budget to get another source control package unless it is *truly* required.

I've talked with MadCap about this, and they claim that source control is unnecessary for Flare, unless you are worried about people stepping on each others' toes in individual topics (as the last person to save wins, though they do get a message saying the content has changed when the first person saves...yay real-time transforms!), or of course, you want the versioning of SC, or need to integrate with your developers.

I don't mean to advocate that method -- I think what is appropriate should be dictated based on the actual needs of a team. All of our writers can work in any area of the project (we don't divide work along content lines, etc.), but with over 6000 topics, the chance of working in the same area is very small.

Just offering one team's method of dealing with source control.

[SteveS]

After using source control for a while, I have to agree with Andrew.

Source control is really (IMHO) by programmers, for programmers. Give the complexity of their work, the ability to roll back a couple of days wotk is vital.

But, given the nature of our work, a quick rewrite of a body of text can repair damage without the need to roll back. Ours is a more forgiving field. Source control is a form of frustration for little gain.

</soapbox>

[beagley]

Hi-- a quick two-cents from someone still shopping for Flare--

I've used source control using RCS on the source files for all of my documentation (we write in plain text and then compile with DocBook tools).

The advantage comes when many people are working on a document and I can compare versions to see what was changed.

I think that's a perfectly good reason to pursue source control with Flare... or is there a better way to know what my colleague changed, on those rare occasions when it becomes an issue?

[RamonS]

I think in regards to Andrew's point, source control with Flare would be more appealing if MadCap put native support for FOSS source control systems like CVS or SVN rather than to only support expensive, proprietary, platform dependent systems. Still, I highly recommend source control as it can be used as information source for example for tracking project status or historical tracking. I also assume it to be easier to create backups of one repository than from several that may even be spread among various systems/servers.

[mattf]

I use CVS on a DOS shell. I think there is a way to interact directly through the Flare interface with CVS, but it's not one of the default choices and so I never bothered to set that up. It took me a day or two to learn the CVS commands. It's easy and works really well. I'm not using source control just for back-up. Our nightly build system pulls the documentation together from source control just the way it pulls together the rest of the code. Like Ramon says, documentation is code. Having the engineers and the development team regard it and treat it as code is beneficial to me as the tech writer. When it was seen as a last minute "nice-to-have", there was never any forethought about and little conscious support for the work I was attempting to do.

I have only two areas of trouble:

1) The file "Master.fltoc" is UTF-16 encoded, even though it believes itself to be a UTF-8 file. For this reason, it is necessary to always enter this file into CVS as binary (using the -kb switch). I have to remember this each time I'm setting up a Flare project in CVS. (Yes, I've submitted a bug report.)

2) The dictionary file "English <United States> Dictionary.mcdic" has spaces in it, which doesn't play in CVS. Oddly, it's the only file in all of Flare that has spaces.I have always left it out. In fact, I was just coming to the forum today to ask what other people do about this, but I'll start another thread for that.

[ruthen]

We are investigating using Subversion. Currently I have been playing with TortoirseSVN, and the plug-in from PuskOK.

Has anyone used the plug-in with branches?

[Laurah]

If the other writers need to make changes while the help source is checked out, they do so in a (manually created) copy and wait until the system is checked back in, at which point they check it out and fold in their changes. It's clunky but has worked for a year now.

Hi Paul,

We are looking at doing something similar soon, and I would be interested in hearing your experiences about "folding in" the changes. How do you do that? How often do you merge the changes back in? How much manual work is involved in this? Do you use the source control's compare differences functionality to merge?

Also, one idea would be to check the files out onto a network drive, where all writers have access to the Flare project. Flare allows multiple authors to edit the project at the same time, although if you're working on the same topic there may be conflicts. We used to do this for a while, when there were two of us working on the same project, and it worked well - we held daily 10-minute "scrum" meetings in the mornings to determine who was going to work on which part of the project for the day, so that we wouldn't have clashes. It worked for us, although we only did it for a couple of months.

The downside of working on a network drive is that Flare can get pretty slow, but turning conditional tags off helps.

Hope this helps,
Laurah

[siskamoens]

One note: We may be unusual in this, but we are also checking our output into TFS. Not sure this matters except that it has contributed to our issues with Flare-TFS integration because our output lives in an entirely different folder than our help source. We do this because our built product is stored in TFS and our help system is just one directory in that built product.

Ah, finally someone facing the same issues as I do. I work for a bunch of developers who create automatic builds of our software, with my documentation (output) included. This means that we too have to store the output of Flare in TFS - not for source control, but to automate product building.
Paul: did you have any luck getting it to work for you? We are struggling big time here, both with Flare not supporting multiple workspaces (as I learned in another topic) and with command line building output to include it in nightly builds. And our developers are experienced TFS guys!

Siska

[KevinDAmery]

Here's what I do to solve the issue you're running into: I move the output to another folder before adding it to source control. For example, instead of adding C:\Flare_output\Application_Help\Output\HTML_Help\ to the source control, I copy the chm file to a network folder (X:\Documentation\Application_Help\) then add that copy to source control. This avoids the whole issue with temp files changing, because source control never sees the temp files.

Works for us, although ymmv of course.

[RamonS]

I don't put any of the output folders in source control, but I do add the completed help to source control--not so I can recover it, but so that my developers can consistently get the latest help file when they do a build (we're not set up to have them run Flare from command line).

Isn't the help and the content of the output folder about the same? In my experience putting anything compiled into source control just needlessly bloats the whole system and over times is a performance drag. There is no reason why the devs couldn't pull the final builds from a network share as easily. Especially since you copy it out to the network anyway.

[KevinDAmery]

True, but this way we always know what the "official" version of the help is (it's the one I deliberately put in source control). Helps avoid versionitis.

[RamonS]

That is what labeling and branching is for. The last version of a branch is the final version that went out with that release. That way you can also update the help for an older, still maintained version if necessary without screwing things up.

[KevinDAmery]

That is what labeling and branching is for. The last version of a branch is the final version that went out with that release. That way you can also update the help for an older, still maintained version if necessary without screwing things up.

Yeah... but how would I do that with just a network folder? With source control you can go back to previous versions by doing a rollback, whereas with a network folder it all depends on what's on the backup tapes for that drive.

[RamonS]

No, I meant labeling/branching in source control of the source files. If the devs want a compiled version have them compile it on demand. That is what they do when they want an exe or the entire installer package. Basically, treat the documentation in no way different than the source code. Only good things come from that.

[KevinDAmery]

Fair point - except we aren't using command line compiles here, for the simple reason that I can't guarantee that I've finished writing something at any given time. The last thing I want is someone doing a build with a half-worked-on topic in there; I'd rather they get an old version that's complete. So I control the production of the documentation from start to finish, then provide them with a finished product when I'm good and ready

This too is following your "treat documentation like code" mantra: no programmer worth the title would let their code be included in a build until they're confident it's done, so I don't let my documentation be included until I'm confident it's done.

[RamonS]

Exactly, that is why a build from source control is always done only against what is in source control. That means, neither the tech writer nor the developer should check in things that aren't completed and tested yet (tested by the dev / tw). That means that if there is a build it will only include complete portions of the help. Of course, it is understood that the resulting build may be outdated or incomplete in regards to the final release, but so is any interim build of the software.

[doc_guy]

My Flare projects have two different targets. One is a local target and one is a network target. I develop my content (and check my files into source control), and build my targets locally to test them. When I'm ready for my content to be added to the build, I build my network target. That way, the files in the network target are always builds I'm happy with. The script that builds our product has code that copies the files from the network target location and builds those files into the product.

This solved a couple of problems for us. First, our build box is a Linux box, so it couldn't compile Flare (because the compiler needs to be a Windoze box). Second, I only wanted "build-ready" files to be built into the product builds. Third, I only want to check my source files into source control, not my output files. With this method, my output files never get checked into source control.

It's a solution that works for us, at least.

[Skooter]

We currently switched to Subversion/Tortoise SVN from Visual SourceSafe (software developers decision of course).

We never integrated Flare with Visual SourceSafe - preferring to check our files in and out independently. Subversion Tortoise SVN is a more user-friendly source control system, but since you can't readily identify what files are "checked out" (instead you get a working copy of files) you also can't easily manage files in the repository as you could in VSS).

I tried to use the PushOK plug-in for Tortoise SVN, but could not get around an assertion error when trying to bind the project.

Deleting, renaming, or moving files within Flare is therefore slightly problematic -
When you delete files within Flare, Subversion does not mark them for deletion, since a normal Windows delete is performed instead of a Tortoise SVN | Delete.

Similarly, when you move or rename files within Flare, they become un-versioned files that have to be added using Tortoise SVN | Add.
In both cases, the original files in Subversion need to be manually deleted from the repository - otherwise they are restored (to their original location, or with their original name) when a Tortoise SVN | Update is performed.

So we have to do the following as a workaround :

1. Use Flare as normal to Delete, Move or Rename the files, so that all project links (dependencies) are properly taken care of.
2. Use Tortoise SVN | Add to add any moved or renamed files.
3. Make a note of the Restored files that are listed the next time you do an SVN | Update and use Tortoise SVN | Delete to delete those restored files.
(When you perform a Tortoise SVN | Delete on a file, the file is immediately removed from Windows Explorer. Subversion will then delete that file from the repository the next time a TortoiseSVN | Commit is performed.)

If you are only deleting files, an alternative is to:

Ensure that the files you want to delete have no dependencies,
Go to Windows Explorer and perform a Tortoise Svn | Delete on those files.

Painful, but such is the tech writers lot!

[RamonS]

And again, I can only ask MadCap again to implement source control support through the command line. Figuring out the shell commands cannot be that difficult and is likely well documented. While there should be standards ready to go for the major source control systems, anyone can add more for the case that other systems are in use, including home grown systems. The only requirement is that they can be accessed via CLI.
We did that with VSS and TFS and I also did that with CVS and SVN in different contexts. Once it was set, it worked reliably each and every time. Supporting only the proprietary Microsoft API is just not good enough.

[ChrisBradley]

Thread Revival!

My doc department is trying to move our Flare projects to TFS. We have a command line build that publishes a CHM file to a directory where the software devs will grab it and include it in the daily software build. If the devs have a local copy of flare, what is the command line syntax to ensure they get the latest update from TFS before they build the project?

Sorry if this is a lame question, I'm new to TFS and having to navigate the waters alone...