In my current role, I need to produce training material for a software product that has three variations (depending on the licence the user has). The original framework to create these training materials was to have three completely separate sets of PowerPoint slides – one set for each ‘flavour’ of the product.

Coming from a strong single sourcing background, the pain point was that 80% of the content was shared across the three flavours! It was only a scattering of slides throughout that varied between the flavours. The maintenance overhead of having to make updates to three sets of slides for the common content was enormous. Not to mention the scope for errors and inconsistencies between the different variations.

I needed a solution to save time (and my single sourcing sensibility!).

I wanted the ability to include or exclude specific slides based on a set of conditions. (Sounding like Author-it’s variants functionality, anyone??)

The solution

The solution consisted of:

• Marking up slides that were specific to a particular flavour (or flavours) with a condition tag.
• A macro that would ‘publish’ a slide deck for a particular flavour of the product. The macro would remove slides that did not meet the conditions for the required flavour of the product.

Adding conditional tags to the slides

Marking up the slides with the conditions was just a matter of deciding on a convention for the conditional tags. I decided that my conditional tags would begin with ‘<<Cond’.  I put the conditional markers in the notes section of the PowerPoint slides. The following screenshot shows an example of the conditions.

The actual conditions that I could include are totally arbitrary – as long as they start with ‘<<Cond’ (because that is what the macro will look for).

Running the macro

When I run the macro, it:

1. Searches through all of the slides in the deck for conditions starting with ‘<<Cond’.
2. Displays a list of these codes for me to select which conditions I want to apply to the slide deck. If a slides contains:
   • One or more conditions, if any condition on the slide matches one of the selected conditions, the slide is included.
   • No conditions, it is included only if the Include slides with no conditions? check box is selected (see screenshot below).
3. Goes through each slide testing the conditions. If it fails the test, the slide is deleted.

For example, if I wanted to build a slide deck for the ‘Strawberry’ version of the product, I would select the conditions as shown in the following screenshot.

After running the macro, the slide deck would contain only slides that either had '<<CondProduct=Strawberry>>' in the notes section or had no conditional tags at all.

It is rough. It is rudimentary. But it lets me single source, which is what I like.

As a side, I have another macro which goes through the slide deck and removes all of the conditional codes from the notes – just a quick tidy up macro.

If you would like any more information or would like to use my macro, please contact me.

A feature lacking in Author-it is the ability to get a list of the variables defined in your library. Sure, you can do screen captures of the variables from within the Author-it Administrator, but it is not very convenient, especially if you want to manipulate the variables in a spreadsheet or text file.

Below is how I get a list of variables, and their default values, from Author-it. There are two methods – depending on whether you are using an SQL Server or Jet library.

Notes and warnings:

• Only use these methods if you have a sound knowledge of SQL and databases. Using these methods you access the Author-it database directly. Although the SQL commands are ‘read-only’ commands, if you do not know what you are doing, you could cause serious damage to your Author-it Library.
• If you are using a Jet library, you will need the database password. This password can only be obtained from Author-it, so do not ask me for it (and they may not give it to you)!

Using SQL Server 2005

1. Open Microsoft SQL Server Management Studio and connect to the server.
2. Expand the Database node in the tree and select your Author-it database.
3. Right-click on your database and select the New Query option.
4. In the query window, enter the following query:
   

   SELECT NAME, DESCRIPTION, VARIABLE_VALUE FROM VARIABLE v, VARIABLE_OBJT vo

    WHERE v.VARIABLE_ID = vo.VARIABLE_ID

      AND vo.OBJT_ID=0

      AND vo.JOB_ID=0

    ORDER BY NAME

5. Click the Execute button.
6. In the Results tab, right-click and select the Select All option.
7. Right-click again and select Copy.
8. Paste into Excel.
9. Format and print.

Using Jet and Microsoft Access 2007

1. Open the Author-it library in Access:
   • Open Microsoft Access.
   • Click the 'Orb' and select the Open option.
     
   • Navigate to the folder where your Author-it library is located.
   • Show all files by selecting 'All Files (*.*)' in the file type drop-down list.
     
   • Select the Author-it library and click the Open button.
   • Enter the database password and click the OK button.
2. From the Ribbon, select the Create tab and then click the Query Design button (in the Other group).
   
   The Show Table dialogue box is displayed.
3. Click the Close button.
4. From the Ribbon, click the View button (in the Results group) to show the SQL query window.
   
5. In the query window, enter the following query:
   

   SELECT NAME, DESCRIPTION, VARIABLE_VALUE FROM VARIABLE v, VARIABLE_OBJT vo

    WHERE v.VARIABLE_ID = vo.VARIABLE_ID

      AND vo.OBJT_ID=0

      AND vo.JOB_ID=0

    ORDER BY NAME

6. From the Ribbon, click the Run button.
   
7. Press Ctrl-A to select all of the results.
8. Press Ctrl-C to copy the results.
9. Paste into Excel.
10. Format and print.

The new Author-it Web Help is a great leap forward from the frame-based HTML previously output by Author-it. I am a fan of it and we are starting to use it in our new help systems where I work.

However, while it has a slick new look with clever dynamic elements, it is not as easy to customise as the old-style HTML output. Basic configuration (such as hiding buttons or setting the default home page) requires you to delve into the stylesheets and HTML. For authors not comfortable with HTML and CSS my Author-it Web Help Configuration Wizard attempts to take away the pain to do this basic configuration.

The next level of configuration – to create a brand new theme – requires delving even deeper into the CSS of the Web Help. Be prepared to get your hands dirty...

The basic process I use to create a new theme is to:

1. Make a copy of the original Web Help template folder for the new theme.
2. Duplicate the Web Help objects in Author-it and point the new objects to the new Web Help template folder (for example, a new Book template, Media object, and Publishing Profile).
3. Update the images in the \extjs\resources\images\default folders for your new theme. Alternatively, you could try getting a theme from Ext JS http://www.extjs.com/ (the web component used by the Web Help). Try this search: http://www.google.com/cse?cx=001733999371871106761%3Ajgc8jk2xgwe&ie=UTF-8&q=themes&sa=Search
4. Update the ext-all.css stylesheet in the \extjs\resources\css folder (or the stylesheet for the theme downloaded from EXT JS). This is where it gets tricky because there are nearly a thousand elements in this file. It takes patience to locate the right element to update! The specifics of what needs to be updated in the stylesheet is too detailed for this post.
5. Update the images in the images folder (for example, the feedback and edit buttons).
6. Publish and test.

As you can see, the trade off for the new slick help is a more complex method to customise a new theme. But it is not too much of a stretch if you have intermediate CSS skills, basic image manipulation skills, and an ability to ferret through the stylesheets and comprehend what they are doing.

You can see the results of my efforts here. If you would like to use this theme, or if you have requirements for a theme of your own, contact me.

A bit slow getting started this year, but here are the details of the next Qld Tech Writer event. If you are interested in giving a short 20 minute presentation to the group, please let me know and we can arrange a suitable venue.

Details

Date: Wednesday, 10 March 2010
Time: 5.30pm
Venue: TBA 
RSVP: Friday 5 March 2010 - http://bit.ly/asWjzd

The Author-it Web Help Configuration Wizard has been updated to be compatible with the latest Author-it release (5.3.209.6248).

Specifically, it has been updated to support the new option to specify the default text to be used in the feedback email.

Access the wizard here: http://www.hamishblunck.com/authorit/aitconfig/

If you have used the wizard before and you entered your email address, you can re-enter it to retrieve your settings (and then make the update for the feedback text).

A word of warning: Backup your template folder before copying the new configuration files across. Also, if you have made additional changes to the index.htm or webhelp.css files you will need to merge these back in.

A not-so-serious look at technical communication through some random stats pulled from the internet.

References:

• http://www.bls.gov/oco/ocos319.htm
• http://www.stc.org/about/index.asp
• http://online.onetcenter.org/link/summary/27-3042.00
• http://en.wikipedia.org/wiki/WinHelp
• http://www.readthefuckingmanual.com/
• http://comm6480rpi.blogspot.com/2009/09/clippy-misunderstood-animated.html
• http://tinathetechwriter.blogspot.com/
• http://www.historyofscience.com/G2I/timeline/index.php?id=419
• http://www.laynetworks.com/history2.htm
• http://www.stc.org/about/history01.asp

I have updated my Using Author-it Variants for Multi-release Software document with information about removing older releases and an FAQ. It has also been tested against Author-it v5.3.207.6063.

Go here to read the document.

If you use this solution, please register for updates.

An invaluable tool I have been using for the last year or so is Texter. Developed by Lifehacker (also a great blog in itself) it saves you loads of time by replacing a pre-defined abbreviation with text as you type.

How it works: Texter monitors what you type. When you type in a pre-defined series of keystrokes (a ‘hotstring’), Texter replaces those characters with a longer section of text. For example, if your company name is Primatech Paper Company, you could set up a hotstring of ppc. When you type ppc, Texter replaces it with Primatech Paper Company.

Texter works with any Windows application.

An example I use at work is below.

Tip: To avoid inadvertently inserting expanding text mid-word I use the full stop (or period) before all of my hotstrings. It is unlikely that I’ll type a key sequence of a full stop and then a letter directly after it and not want it expanded.