Subversion - To Plug-In or Not to Plug-In

[parsonsv]

Hi all

For the past few years, the technical writers have shared a network location for our help files, edited them in that location, and zipped the source to upload into Subversion whenever we had new changes to submit.

Now that we have SSD drives in our machines, we want to take advantage and run the help from our local drives. However, with more than one writer working in same help file, it's impossible for everyone to run from their local drives (someone would have to share the file from their computer and the other would access it via the network share).

That got me thinking about Subversion. If, instead of zipping the source and submitting it, we stored the unzipped source in subversion, we could check it out locally and work in it, and then submit our changes through subversion. Everyone could have a local copy.

As I investigated this option, I learned that people are using Plug-Ins with Subversion (the most common being PuskOK). I know that in Windows Explorer, I can SVN Commit my changes, so I'm not sure what the Plug-In is all about. Why would I want to use it? Does anyone know?

Also, I know if I try to upload a file through Subversion with changes that are dated older than changes already submitted, I'll get an error. I feel this scenario is likely with the case of multiple people editing the same help file. Any idea if there are issues with submitting? Have you encountered any gotchas you want to share?

[gfranceschini]

I'd like to bump this.

We're starting to move all documentation into SVN and the remaining piece is our Flare output. I've looked in the forums and seen that PushOK is getting traction - but it's hardly positive feedback I'm seeing. Is anyone simply using Tortoise? If so, any issues? What does the workflow look like? I'm assuming it looks like regular SVN/Tortoise workflow - I don't expect any Flare related oddities, but it's always nice to be forewarned.

[RamonS]

I'd go with Tortoise for now. That costs less and you seem to be familiar with it. As Flare is concerned, it is just a bunch of files stored locally. Just make sure that you check out all those files that the project needs to write to.

[gfranceschini]

Thanks, Ramon. Yes, a few of us have used Tortoise for a while, and as we're thinking things through we just not seeing a downside to keeping on using it. Thanks for the reply.

[Andrew]

I'd like to bump this.

We're starting to move all documentation into SVN and the remaining piece is our Flare output. I've looked in the forums and seen that PushOK is getting traction - but it's hardly positive feedback I'm seeing. Is anyone simply using Tortoise? If so, any issues? What does the workflow look like? I'm assuming it looks like regular SVN/Tortoise workflow - I don't expect any Flare related oddities, but it's always nice to be forewarned.

I use TortoiseSVN with Flare. The only annoying things particular to Flare are that I exclude the Output, Analyzer, and Projects\Users folders from source control, because they don't contain anything that needs to be under source control, change frequently (and often in the absence of other real changes to the content), and generally just annoy me by clogging up the file commits / updates with meaningless stuff. There are other folders I've considered removing as well (such as Projects\Reports) but I haven't gotten around to it yet...removing that stuff once it's in source control is a pain.

[TechnicalDisaster]

My documentation team also uses Tortoise SVN with Flare. We have 20 doc writers with 80+ guides and release deliverables. We are in Agile development with 3 major releases and 4 minor releases a year.

We are in the process of converting from FrameMaker 7.2 to Flare 6.1. We have moved all of our release deliverables over to Flare and have just begun our guide conversions. Our team was not using SVN prior to Flare, so we all had to learn the workflow together.

In our experience:
SVN Locks are a nightmare. Do not use locks unless absolutely necessary. I was never able to make locks work with Global importing, since I needed to get the locks on the global project and the the locks on the child project. We ended up adding a hook to SVN that prevents locks from ever appearing again. Like Andrew, we also added hooks that prevent the Output and Analyzer folders from being added to SVN.

It took awhile for the team to learn not to copy and paste folders checked into SVN. Probably a no-brainer to someone with a ton of experience with SVN, but we got hung by it a few times.

Here is what we added to our SVN user's guide for workflow:

Working in Chunks

The best method to use when working with Flare and in SVN is to work in chunks of like tasks or within folders. For example, it is best to work in one enhancement folder and commit those changes before moving to tasks in the second enhancement folder.

This method is recommended because it allows you to commit your changes frequently, allowing others writers to access the information as soon as you are finished with it, and it allows application administrators to revert to previous versions of files, if necessary, when troubleshooting Flare and SVN issues.

For example, say you need to complete the following tasks:
Add three topics to enhancement #1.
Add two topics to enhancement #2.
Modify existing content in enhancement one folder.
Modify existing content in enhancement three folders.
Modify conditional tags on three TOC items.Delete four topics.

The best course of action would be to complete these tasks in the following order, but performing an Add, Commit, and Update in SVN between each task:

Add all five new topic pages and add links to the TOC.
Change the conditions on the three TOC items.
Modify the existing content for enhancement #1.
Modify the existing content for enhancement #2.
Delete the four topics.Perform an Add, Commit, and Update in SVN.

[rkirkhart]

We noticed that if you add your Flare project to your SVN repository the first time by "binding" the project to the SVN source control, Flare is smart enought to NOT bind unneccessary folders like Users and OUtput. That's a good thing