Adventures in Visual Studio Online

This forum is for all Flare issues related to using Source Control.
Post Reply
ToddPh
Sr. Propeller Head
Posts: 140
Joined: Wed Jan 30, 2013 2:41 pm
Location: Kirkland, Washington

Adventures in Visual Studio Online

Post by ToddPh »

I apologize if this post seems haphazard. I just spent several hours working through many configuration options looking for a smooth solution and thought I would share what I have settled on as a working solution.

In my current gig I am a solo writer supporting an Agile environment. With the impending release of a major online service we will be bringing three more writers onboard very quickly. So my current installation for Flare 8 using Tortoise SVN on my local computer will very soon be completely inadequate. Our developers use Visual Studio and TFS, so that seemed like a good option, but alas getting the proper permissions established has been a nightmare thus far. (remember, agile... very busy... contractors = not important)

When I read about Microsoft releasing Visual Studio online as a "free" service for up to 5 team members, I thought this would be a perfect solution. In case you're thinking the same thing and haven't read up on the idea here in the forum, it works... sorta. What works is that I have configured a team project using Visual Studio Online anmd I will be able to add my new coworkers once they start. We will use TFS for source control, but the source control functions will be handled through TFS and outside of Flare. :( I will continue to tinker with authentication methods since this is where it fails to bind to source control in Flare. If you are interested in pursuing this as an option for a small team or solo use, currently at no cost, then here are the steps that have gotten me to this point:
  1. Download and install Team Explorer for Visual Studio. I am using the 2010 version, but the 2012 version is available to download at http://www.microsoft.com/visualstudio/eng#downloads. You can search Microsoft.com for the 2010 version if you prefer.
  2. Install all updates. This means Service Pack 1 if you use the 2010 version and http://support.microsoft.com/kb/2662296.
  3. The Visual Studio site uses Windows Live ID to login, and rather than entangling it with my personal Live ID I created a new ID based on my work email. This is a matter of personal preference, but if you opt for a new ID it is smoother to register for the ID before you create your Visual Studio account.
  4. Create your free account at VisualStudio.com. Make note of the URL that is created for the project as this is what you will use for the server name in Team Explorer.
This should be enough to setup your necessary accounts. Next, you need to configure your local computer to integrate with TFS for source control.
  1. Create a working folder on your local drive to contain the local mapped working files (I used C:\Work)
  2. Start Visual Studio. Team Explorer is really just the Visual Studio shell and doesn't do muich of anything on its own. Once it is connected to a TFS server it gives you access to all of the features of TFS and is our local home for source control under this strategy
  3. Follow the steps to add a server connection (may be slightly different between versions, but basically just providing the URL you created when you opened your online account). Use the HTTPS protocol to connect. I found that the full format for the address worked best (projectname.visualstudio.com/tfs/DefaultCollection)
  4. Copy your Flare project files in their current working folders into the new working folder you created in the first step. Yes, I will admit to a healthy amount of paranoia when working with files: I copy them in just in case they are lost in some bizarre bi-universal subspace rift, or in case I fat-finger something. In any case, copying means you still have your original source files untouched if this doesn't work out or if you decide that TFS isn't for you.
  5. In Team Explorer (the right-hand pane in TFS) expand your project and then double click Source Control. This opens the Source Control Explorer.
  6. In Source Control Explorer, under the Folders pane, right click the project name and then click Add Items to Folder. Browse for your new work folder (where you just copied all of your precious Flare projects) and add all of the folders.
  7. In the central workspace (central pane) control-click each folder that you just added to highlight them. Right click and then click Check In Pending Changes. Add some comment to describe the initial checkin and click OK.
At this point, if everything went properly, your Flare projects are now in TFS source control hosted out in the cloud with a local copy on your computer. That's the good news. The not-so-good news is that to work on your files you need to check them out in TFS before opening them in Flare. From my previous experience doing this on another gig, you quickly get used to it and will develop your own processes whether you check out the entire project (good for one writer) or check out individual files (works well for multiple writers on a project).

I hope this helps.
Todd
Todd
Image
When puns are outlawed, only outlaws will have puns.
ToddPh
Sr. Propeller Head
Posts: 140
Joined: Wed Jan 30, 2013 2:41 pm
Location: Kirkland, Washington

Re: Adventures in Visual Studio Online

Post by ToddPh »

I posted a feature request to include the option to pass login credentials when binding to source control.
Todd
Image
When puns are outlawed, only outlaws will have puns.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Adventures in Visual Studio Online

Post by NorthEast »

Thanks for the information - I'll be interested to know if you manage to get Flare to bind directly to the online TFS.
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: Adventures in Visual Studio Online

Post by RamonS »

ToddPh wrote:In my current gig I am a solo writer supporting an Agile environment.
My deepest and most sincere condolences! Agile is nothing more than a plot by consultants to make money. I am on an Agile team and at best it replaced some problems with other problems while not addressing the biggest problems we have. And work got much more difficult causing projects to last longer. In the end each sprint is just a mini waterfall. Business analysts spend the first week figuring out what they want, developers spend the second week coding, business analysts spend the third week changing their minds, and everyone in QA and tech writing gets the morning before demo to do their jobs. Oh well! :roll:

Thanks for sharing the steps. In general, unless the source control system modifies or adds to the Flare files any source control system can be used with its native clients. What would be great is to have Flare act as the client to VS Online as I see that to become a very popular option for small tech writing / development teams. Too bad that you were not allowed to hook into TFS already in place. That would make automated builds with help much easier and QA could use TFS to report bugs against the docs. Shows again that some don't understand that end-user docs are as important as source code. Why give some parts of the product top shelf treatment and other parts not?
I did point out to MadCap already that integrating with Online VS is needed. I suggest you add a feature request as well, maybe they get around to putting this in at some point soon.
ToddPh
Sr. Propeller Head
Posts: 140
Joined: Wed Jan 30, 2013 2:41 pm
Location: Kirkland, Washington

Re: Adventures in Visual Studio Online

Post by ToddPh »

It looks like the only thing we are missing in order to use VS Online is the ability to pass credentials along when we bind to the service. I really do feel this could be a huge benefit to solo writers and small documentation teams. It already is a benefit even with the need to use the stand-alone client to manage the source control, but I get all nerdy when I start thinking about the potential to use this as integrated source control for Flare. Oh well, perhaps someone in Madcap development will agree and provide this feature as a minor update.

I've had difficulty adjusting my thinking to the agile environment. I read a quote in someone's forum tagline that went soemthing like "Agile Technical Writer: Where your document is obsolete before you finish it." At first I laughed, but then I realized the truth in the statement and it helped me change the way I look at my role here. Now I see that a big part of what I do for the team is to facilitate and track the discussions where the decisions are made. Under the traditional waterfall method, I was a priest translating the divine word of the developer into the mortal realm of understanding. In the Agile world I am become the squeaky wheel that irritates people until they make a decision. I'm still deciding how I feel about that. :p
Todd
Image
When puns are outlawed, only outlaws will have puns.
BaritoneJP
Propeller Head
Posts: 49
Joined: Mon Jun 02, 2008 9:12 am
Contact:

Re: Adventures in Visual Studio Online

Post by BaritoneJP »

ToddPh wrote:. In the Agile world I am become the squeaky wheel that irritates people until they make a decision. I'm still deciding how I feel about that. :p
I feel the same way. I write documentation based upon the vague information in a story to rewrite the same topic the morning before the demo. (and sometimes again after the demo)


We use Visual Source Safe for a team of 4 writers and the only issue we have is the dreaded "a new version exists on the server" message.
Thank you for your comments and help with my quandary ...
Jamey
ToddPh
Sr. Propeller Head
Posts: 140
Joined: Wed Jan 30, 2013 2:41 pm
Location: Kirkland, Washington

Re: Adventures in Visual Studio Online

Post by ToddPh »

Since posting this thread I have been joined by two more writers. We're still using TFS through Visual Studio Online with mostly good results. We did have the "A newer version exists on the server" scenario the other day. I thought originally that one of my colleagues had made a change to three files while I was working in the project, but it appears to have been something else as she was able to convince me that she wasn't in the project at all for the entire day in question.

The moral of this story may be that TFS online isn't a perfect solution. I know, big surprise. :)

I am noticing that I spend time helping our new writer understand that Agile documentation is "just good enough" and to let go of the idea that we will be publishing perfect documentation until the developers are no longer involved.
Todd
Image
When puns are outlawed, only outlaws will have puns.
BaritoneJP
Propeller Head
Posts: 49
Joined: Mon Jun 02, 2008 9:12 am
Contact:

Re: Adventures in Visual Studio Online

Post by BaritoneJP »

See this post on the "newer version exists on the server" message http://forums.madcapsoftware.com/viewto ... 68&t=15942

Funny, the saying here is "just enough, just in time" ... and I'm trying really hard, in my mind, not to think that synonymous with "waterfall".
Thank you for your comments and help with my quandary ...
Jamey
mikgam
Jr. Propeller Head
Posts: 1
Joined: Mon Jul 08, 2013 11:43 am

Re: Adventures in Visual Studio Online

Post by mikgam »

Sorry to revive this old thread but I was reading through all the TFS posts to help determine if the TFS integration is going to work for us. I'm a dev/build/release engineer and not a propeller hat writer, but want to get our writers into source control and automated build process.

ToddPh, did you ever get the authentication with the hosted xxxx.visualstudio.com service? One idea that might help is to go into the windows Control Panel, and find the Credential Manager. That lets you define what credentials should be used when an application tries to use a resource. For example, you can "Add a generic credential" and enter the https://xxxx.visualstudio.com and then the username and password. Since the online TFS service uses the Microsoft/Live/Hotmail/<insert this week's name of it> account service for authentication, maybe you can set the credentials in there, and then when Flare tries to access that internet URL, Windows/Flare will use those credentals to talk to the server.

I had difficulty even getting Flare to bind with our in-house TFS 2010 server. I ended up entering the full URL to the TFS collection into Flare since nothing I tried with Flare's add/browse buttons worked for me.
ToddPh
Sr. Propeller Head
Posts: 140
Joined: Wed Jan 30, 2013 2:41 pm
Location: Kirkland, Washington

Re: Adventures in Visual Studio Online

Post by ToddPh »

I actually surrundered in frustration a couple weeks after my last post. The other two writers on my team work on shorter documents, mostly in Word, and don't have the need for source control that I have. They also were less able/willing to put up with the hoops of using the TFS client to manually check in and out. So it seemed the better option was to give up on TFS and I went back to a local SVN for my source control with frequent builds out to other locations to provide some fault tolerance.

Our current publishing process is using Google Drive to share document builds, and using Trello (http://www.trello.com) for low level project management including a card that tracks the links to the current build of the doc. It's working fairly well for us and for our regular customers. It is a pain to get people mto understand the different tools when they first start, but that's part of the chaos... er... charm of our environment.

For basic information's sake, I did try various configurations with the Credential Manager, since like you I thought that would do the trick. No luck there, though. I think it will require a custom plugin for Flare to make the connection work, because TFS Online must have a login when you connect, and the format is different from the standard TFS connector in Flare.
Todd
Image
When puns are outlawed, only outlaws will have puns.
Post Reply