I need a Flare/Source Control Primer

This forum is for all Flare issues related to using Source Control.

I need a Flare/Source Control Primer

Postby docudramaqueen on Tue Nov 08, 2011 9:39 am

These are some basic questions, but it's the first time I've been solely in charge of a project. I am, essentially, the tech writing department. I am building a brand new help system for an existing software product. There is an extensive collection of KB articles that have been written by non-writers over the years that I will convert into the basis for the help system. SMEs will continue to submit articles on SharePoint, which I will enter into Flare. I'll be the only Flare user, so the problem of having multiple users is not a consideration. We release updates to our product on a quarterly basis, so there will be frequent updates to the help system.

I find I'm confused by several things:
1. How badly do I need source control?
2. What are the risks of not having source control in my situation?
3. Is it practical to try to create my own "version control" by implementing some numeric system into my file naming conventions, and is that just a stupid thing to do?
4. What is the relationship/overlap among Subversion, Source Safe, TortoiseSVN, SmartSVN? Are they all different brands of the same tool, or do the SVN tools only serve to integrate authoring tools to source control tools?
5. Which leads to, what exactly is the whole dynamic structure among authoring tools, source control, and versioning? And does Flare 7 do all of that now?
6. And finally, what do you recommend?

Propeller Head
Posts: 27
Joined: Thu Oct 20, 2011 11:01 am
Location: Mt. Angel, OR

Re: I need a Flare/Source Control Primer

Postby RamonS on Tue Nov 08, 2011 1:58 pm

Here are my 2 cents:

1. You do not need source control as lone writer, making daily (or more frequent) backups to a network share that gets backed up is sufficient as long as you keep separate copies for each mile stone (new set of topics added, releases, etc.). Do not overwrite the copy each time, because then you cannot go back to what you had a week ago. This will be not a problem with source control as it keeps individual copies from each check-in.

2. The risks are that you think you no longer need a backup and a day after you deleted it you need it. Also, without sticking to a proper folder nomenclature you will eventually lose oversight. Also, you will eventually have to compress the backups into ZIP or better 7zip archives, so grabbing files will take some uncompressing and the archives may get corrupted (although that is rather rare)

3. That is possible, but in order to maintain sanity label entire copies of the project, not just individual files.

4. Visual SourceSafe (VSS) is the old source control system from Microsoft, it got replaced by Team Foundation Server (TFS). So if you want Microsoft, use TFS. VSS is on its way out. Subversion (SVN) is an open-source option that is easy to install, easy to administer, runs on various OS, and has several graphical front ends, such as TortoiseSVN. VSS, TFS, and SVN are three different things and while they do generally the same stuff more or less well they are not the same and not compatible with each other (although there may be a VSS to TFS converter, but that is of no relevance for you). AFAIK you need to buy VSS or TFS, whereas SVN is just a download away. Did you check what the developers currently use? They will have a source control system in place, so there is typically not much point in adding another one (and if they do not have one, run fast and run far).

5. Flare will act as client to any MSSCCI API enabled source control system (any system that runs with VisualStudio without requiring plugins) or Subversion. You will initially check in all project files and after that each check out/check in cycle will attach a sequential number to the file. You can further set a version label that will get applied to all files in a project (some may have not been changed at all, while others are changed 50 times and have a different sequence number). This labeling is also called versioning. The terminology is grounds for religious wars, some call it "check in" while others insist it has to be called "commit". In the end it is the same. Versioning has the advantage that you can quickly retrieve the complete set of files for a specific version. Flare supports all this rather well.

6. My recommendation is to hook into the source control system that development already has, unless it is BitKeeper or Vault or GiT or CVS or something that Flare doesn't support natively (there are plugins for CVS that will allow Flare to use CVS, there may be plugins for other source control systems as well, not sure). If they do not have one (see above, better look for a new job then) or are totally against having you use it as well (can't think of a good reason, you won't be touching their code) then it depends on what you budget is. If you do not get funds or rather spend it on other tools then go with Subversion. It is a bit intimidating at first and in some constellations performance isn't great. You can go the easier route with less optimal performance as I described here:
OR you can buck up and learn how to use the command line tools and hook Flare up to Subversion using the native SVN protocol, which is faster than using HTTP(S).
BUT regardless if which source control system you use, ALWAYS make your own BACKUPS! Get an external USB drive or space on a network file server. You can get away with making less backups, but I've seen servers crash and source control systems going belly up before. The paranoia of everyone keeping plenty of local copies saved the company in that case (it didn't save the IT guy who was too lazy to replace the failed RAID drives until the last one died). Backup, backup, backup!

Hope this helps.
Senior Propellus Maximus
Posts: 4291
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: I need a Flare/Source Control Primer

Postby docudramaqueen on Tue Nov 08, 2011 2:16 pm

Thanks a bazillion! That answers most of my questions. Yes, we do have a source control system in place, so luckly, I won't need to run. I think we may set my source control separately because the development team is in a remote location and on different servers than customer support (but that's based on my conversation with my boss, the customer relations vp, not the head of the dev dept.). At any rate, you've helped clarify the difference between source control and the clients that provide communication with it. Sounds like the Flare/Subversion combo will meet my needs and not add to the cost we're about to incur buying the Flare suite....
Again, thanks.
Propeller Head
Posts: 27
Joined: Thu Oct 20, 2011 11:01 am
Location: Mt. Angel, OR

Return to Source Control

Who is online

Users browsing this forum: No registered users and 5 guests