ITauthor

The context menu for a span in Flare 5

Madcap Flare 6.1 has been out for a while now and, if you haven't already, you really should upgrade to it if you're a Flare user – and if you're a tech writer and you're not using Flare to produce online help then do yourself a favour and go and take a look at it.

Release 6.1 is confirmation that Flare is the best documentation creation tool out there. In particular, for me, this release is important because it allows you to use Subversion (SVN) from within Flare, which was broken in 6.0.

However ...

Isn't it annoying when a new release of a software application removes something that you'd got used to using in previous releases? In Flare 6.1 – for no discernable reason – you can no longer change the attributes of a span by clicking on the "span" marker. We use the Name attribute of a span with a certain class to create a link to our own home-grown glossary popups. This worked great in previous releases, as follows:

• Select a word or phrase
• Choose span.glossPop from the Styles list
• Click "span" > Name
• Add the appropriate glossary reference

In 6.1 you can't do this any more. Now, just to increase your click count, you have to get to the Manage Named Elements dialog box from the Format menu.

Okay, so there's a workaround. But why remove something that was useful and we'd got used to using? Is it a bug or is there some sort of rationale to this change? I'll raise a Support call and report back.

But in my view more clicks to achieve the same result is never a good thing.

The title of this post pretty much says it all. We were using the PushOK plugin to allow us to check files in and out of our Subversion (SVN) version control system from within Madcap Flare. When we upgraded to 6.0 this broke and we duly reported it to Madcap. After a bit of to-ing and fro-ing of questions/answers with my colleague Graham, Madcap promised to try and fix the issue for the next release.

And, lo and behold, version control is now working again in release 6.1.

Thanks Madcap - much appreciated!

A word of warning for Flare users who also use the Subversion version control system (SVN). The PushOK plugin that provides SVN support in Flare does not work in Flare 6. As a result, although my team have licences for Flare 6, we may stick with Flare 5. If you're considering an upgrade to version 6 you may want to think again if you're currently using the PushOK plugin.

Flare has had built-in version control support for some time now - but only for Microsoft's Team Foundation Server and Visual Source Safe. If you use a non-Microsoft version control system you have to make other arrangements.

If you're a CVS or SVN user then, of course, you can just use something like TortoiseCVS or TortoiseSVN from within Windows Explorer. But in the past Madcap have pointed Flare/SVN users in the direction of the SVNSCC plugin produced by PushOK Software as a solution that allows you more or less the same functionality offered to TFS/VSS users, in terms of being able to work with a source control repository directly within Flare.

This worked OK in Flare 5. It wasn't brilliant, it was a little clunky, but it did work, and it provided real benefits. Specifically it made it easier for writers to update the repository and it made it less likely that you'd forget to get the latest version of a file before starting to work on it. Using the plugin has definitely resulted in fewer version conflicts to resolve.

Unfortunately, after installing Flare 6, try and get the latest version of files and you get this:

Unexpected exception: Access violation - KERNEL32.dll

After clicking OK, the Progress dialog box shows an error message like this:

Querying source control server. This could take several minutes.
: D:\Alistair\ITauthor\Flare-demo-project\itauthorflare\: CustomScc:GetLatestVersion - call failed with error code -15 (Nonspecific error.)

The source control operation finished with warnings and/or errors. Press Close when you are done reviewing the messages.

This is really disappointing for a number of reasons:

• I'd obviously prefer us to use the latest version of Flare rather than having to stick on version 5.
• Flare 6 has been out a few weeks now and the forum shows no positive response from Madcap or indication that they're going to fix this. Yes, I know the plugin is third-party software, but Madcap do not provide their own alternative and have, in the past, suggested SVN users use this plugin: I found out about it via Madcap.
• I had to push to get my purchase request for plugin licences signed off and right now that's looking like a bad decision. I don't want to use something else. I don't want to write off that purchase. I won't get another similar purchase signed off next time.
• I generally have a high regard for Madcap, but in this instance I feel they've let me down. Subversion is not some weird, new, little used system. If you have Microsoft blinkers on you might think that, but you'd be wrong. Subversion has been around since 2000, it's the successor to CVS and is used in software companies around the world.

For more tales of Flare/SVN woes go to: http://forums.madcapsoftware.com/search.php and search for pushok.

I've got a MadCap Flare project that I want to publish as open source code for anyone to go and download. It turns out this is extremely easy to do using Google Code. And Google Code has the benefit of allowing you to sync your work with the online source files using SVN (Subversion).

Multiple people can work on the project simultaneously and each time you open the Flare project the SVN plugin for Flare asks you if you want to use the most up-to-date files from the online repository. When you've finished making changes you just commit your changes, straight into Google Code, without having to leave Flare.

Here's how to create a project in Google Code and add a Flare project.

Prerequisites:

• For the initial upload of files into a Google Code project I'm using TortoiseSVN. You can download this from http://tortoisesvn.net/downloads. TortoiseSVN allows you to work with a Subversion repository from the right-click menu of Windows Explorer.
• You will sign into Google Code using a Google account, so you need one of these if you haven't got one already. If you use Gmail you've already got a Google account, so use that.
• You are going to commit files into a publicly viewable repository. Even if you delete a file from the repository, people will still be able to browse previous revisions of the project and view the file. Versioning repository systems like Subversion are designed to keep a historical record of everything that happened to the repository, so there's no easy way to remove all trace of a file that you didn't mean to upload.* So, before adding a project, make sure that you remove any files that you don't want other people to see.

To put a Flare project into Google Code:

1. Go to http://code.google.com/p/support/wiki/GettingStarted and read through the information about project hosting.

2. When you're ready, go to http://code.google.com/hosting/createProject, fill out the simple form and click Create.

   You will now have a Google Code project with one project member: you (or, to be more precise, your Google account).

   You are the project owner. To allow other people to commit changes to the project, you can add more project members from the Administer tab.

3. Click the Profile link (top right of the page).
4. Go to the Settings tab and copy your googlecode.com password.
5. Now go to Windows Explorer and browse to the directory that contains the Flare project you want to add.
6. Within the project directory select and cut the Analyzer and Output directories.

7. Paste the Analyzer and Output directories somewhere outside of the project directories.

   This is to avoid these directories being added to the repository.

8. Do the same to the Project/Reports and Project/Users directories, moving them out of the project for now.

9. Right-click your Flare project directory and choose TortoiseSVN > Import.
   

10. In the Import dialog box, enter the following as the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk
    

11. When prompted, enter your user name and password.

    These are the user name of your Google Code account (e.g. the bit before the @ symbol in your Gmail address) and the googlecode.com password you copied to the clipboard.

12. Click OK.

    This will now add all of the files/directories to the SVN trunk in Google Code.

    TortoiseSVN displays the progress.
    
    If you have a lot of files in the project this may take some time.

13. When the import finishes, click OK to close the dialog box.
14. Move the Analyzer, Output, Project/Reports and Project/Users directories back within the Flare project directory again.
15. Still in Windows Explorer, in the directory that contains your Flare project directory, right-click anywhere on the background to the main pane of Windows Explorer and choose SVN Checkout.

16. In the Checkout dialog box, enter the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk

    and the Windows path to the Flare project directory (that is, the directory you just imported into Google Code) as the checkout directory.
    

17. Click OK.

    The files you imported are checked out and marked as under version control.

    A little check mark on the file icon indicates that TortoiseSVN knows they are part of a Subversion repository.
     

18. In your browser, go to the Source tab of your Google Code project.

    For example, http://code.google.com/p/itauthorflare/source/browse/

19. Click trunk and you should see all of the files you uploaded.

    

You can now start Flare and open your project and (if you have the SVN plugin) you will be asked if you want to load the latest version of the files from the SVN repository.

* Note: If you forget about clearing out sensitive files and you discover you've uploaded something you really don't want anyone to see, then you can remove all the revisions within the project - in other words you can empty the project and return it back to its initial state before you imported any files. You do this by resetting the repository.

To do this, go to the Source tab in your Google Code project and click the reset this repository link near the bottom of the page. Be aware that this removes everything from the repository, so you should never do this for a project that has an active community working on it, or a project with any sort of a history because this history will be destroyed by resetting the repository. But if you've just started and then realised there's stuff in there that shouldn't be, then it's a way out of a fix.

In my last podcast I talked about a couple of unscripted screencasts I'd recorded for colleagues at work, to show them how to use some Flare extensions I'd created. My question in the podcast was: is something like this (knocked together very quickly) good enough to put in front of paying customers - or potential customers?

Without seeing/hearing the screencasts it's not easy to form an opinion, so I thought I'd let you have a look. Let me know what you think. Are you put off by the ums and ahs, and the little mistakes I correct as I go along, or does it lend authenticity to the demo? Personally, I wouldn't mind seeing a demo like this as part of the user assistance for a product. I think the effects that Camtasia lets you add (zooming in and the rotating cube effect) lend a little polish to make up for the ad hoc presentation style. But it's probably not everybody's cup of tea. What do you think?
 

 
Please note:  When I recorded this it was purely meant for internal use within my company. However, I've had a look at it and I'm confident it doesn't give away any corporate IP. It does, however, reveal (if you look closely) that I had to Google to find a solution to a buzzing microphone shortly before starting the recording!  :-)

Alternative larger format video  (you'll need to wait a little while for it to download, but the picture quality is better).