ITauthor

You know how sometimes you read something and it niggles away at you and you can’t quite get it out of your system? This happened to me with a blog post by Ivan Walsh from November last year. In his post (How do you measure technical documents? What metrics do you use?) Ivan describes how a tech writer got fired from the docs team with the justification by management that “technical documents provide no value”.

This is something we’ve probably all come up against at some point in our careers. Fortunately I work for a company where common sense tends to prevail and a well-reasoned argument, from any source, can be influential. But I know of lots of companies where things are very different. Documentation is often seen as just a cost centre. And when the spreadsheet guys are looking at what’s costing money and what’s winning new business it often looks like documentation is something you could do without. Because – think about it – when did good documentation, by itself, ever win one dollar of new business?

The referee was fantastic!

So, how does a documentation manager prove to the numbers guys that they need to spend money on documentation? It’s not easy. And the reason it’s not easy is partly down to the referee scenario. Think of a great football game (and I’m not talking US-type football here, I’m talking about the football the rest of the world plays). With a great game of football you’re never left talking about the referee at the end of the game. In fact after any game of football you never find yourself talking about the referee unless he did a bad job. You rarely notice the referee if he makes good decisions, lets the game flow, nips trouble in the bud, acts impartially … does his job well. You only notice him when he disallows a perfectly good goal, books the wrong person, consistently favours one team, awards a last-minute penalty when it was a blatant dive, and so on.

It’s the same with documentation. People only start talking about the documentation when it’s incorrect, badly written or absent. With documentation: no news is good news. And this is dangerous. It’s easy to cut the documentation effort because initially no one will notice the difference. The quantity and/or quality of output from the docs team will drop off, but because much of the documentation effort is for new product that’s not going to be released for a while – and even once it is released it won’t be the documentation that customers focus on first – and because the docs team will still endeavour to make sure the high priority work still gets done, it’s going to be a while before this change affects customers. In other words you can get away with it for a while before shit starts to hit fan.

The reverse is, of course, true. It takes a while for cuts in documentation resource to work through and start hurting your customers, but it also takes a while to recover from that situation once the powers that be have decided something needs to be done. In fact, after the problem has been recognised things will continue to nose dive, even after you’ve recruited replacement staff, and even supposing the replacement staff don’t need any training and can magically walk in and start being productive from week one. During this time more and more customers will be hit by the documentation-related problems. A head of steam will build up. Customers will talk amongst themselves about how difficult the software is to use. News might even spread to prospective customers. But by this time the damage that was done was done months before – and there’s no quick fix.

It’s back to the referee scenario. Not only do customers never talk about the documentation unless they’ve got something to complain about, but it’s also true to say that while documentation never won a sale, it is sometimes a contributory factor in a lost sale.

This is the point in proceedings – when you’re doing your best to recover from resource-related documentation problems, but customers are still complaining – that necks are on chopping blocks and axes are poised. And you can bet those necks aren’t the necks of the budget police who wouldn’t let you replace a colleague who left, or wouldn’t grow the docs team in line with the growth in the development team, or who “restructured” the docs team to allow budget to be reallocated to more profitable areas of the business.

Docs are important? Go on then … prove it!

This all sounds very grim. So how do you avoid getting into that mess? You might be convinced that what you do is important – but how do you convince others? How do you prove the value of what you’re paid to produce? How do you answer the question Ivan Walsh got asked: “What metrics do you use to tell if the documents are successful?”

Well I’ve been thinking about this and reading around and there’s surprisingly little out there to help me answer this question. There’s been quite a bit written about what metrics you might use to judge individual technical writers – and maybe measure one technical writer against another – or how you can assess the quality of particular documentation deliverables – for example, the number of comments that were raised during pre-publication review, or the number of documentation bugs raised after publication. But the metrics we’re talking about here are measurements of the value of the documentation effort within your company.

I came across a LinkedIn discussion that mainly concerns the micro-metrics of assessing particular documents or writers (rather than the macro-metrics of assessing the documentation effort itself) but these two quotes, I think, touch upon the bigger picture:

in the final analysis any document is only valuable if it answers the questions the user has so they are not required to make some sort of call to a support person

Keith Oxenrider

A better measure is the readers' view of the documentation. Do they like it? Can they use it to solve their problems? Does the documentation reduce the number of calls to the tech support center? Does the documentation aid the tech support center in quickly resolving client problems?

Dave Gardner

The references to support point to a possible solution.

Donald S Le Vie Jr wrote an interesting and useful article in the December 2000 edition of Intercom (“Documentation Metrics: What Do You Really Want to Measure?”), although he mainly discusses writer-specific metrics that he believes you really shouldn’t bother trying to use – for example, hours per page, pages per hour, documents released per month or per writer, errors per page, percentage of time schedule dates were met, etc. However, he ends the article with some metrics he believes are useful:

• Web-based feedback – e.g. find out what customers want more of, or don’t need, in future versions of documentation
• Customer usability of beta or final versions of documentation. Get them to rate the documentation.
• Team up with Customer Support to make sure it’s recorded when support calls are documentation related.  “Track this information over time to show the decrease in the number of documentation-related calls so you can assign a dollar figure (a quantitative measure) to any metric.”

Le Vie stresses the importance of regularly broadcasting these metrics throughout management.

Conclusion

In the LinkedIn discussion Padric O'Rouark says:

Sell “help” separate and you would find very few buyers.

That’s true, but it’s also misleading. The fact that you wouldn’t pay for something does not mean it has no value. When I buy a bed from Ikea I expect to find instructions on how to assemble it when I get it home. I wouldn’t pay for those instructions separately though. If I was expected to do this I’d just shop elsewhere. As an aside, the poor quality of Ikea’s assembly instructions is one of the things that makes me dislike the company as a whole (that and the fact they try and steer you round the whole store before you get to the checkout, rather than letting you get in, get what you want and get out).

If customer satisfaction is important to a company then the philosophy of doing only as much as you need to do to make a sale, and not one jot more, probably only works if you’re a make-a-quick-buck-and-disappear business, or if you’re competing solely on price and you’re confident customers will accept poor quality products and bad customer service just as long as the price is right.

Customer-facing documentation has no place in a cut-price or fly-by-night business. But in the software business where companies need time to grow and therefore customer retention is important, user assistance is valuable. If you’re trying to sell corporate software then the people with the purchasing power, the decision makers, aren’t the people who are going to be using the software day in, day out. But if you’re in the business for a few years then some of those people who have to use the software in their daily jobs get promoted and end up being decision makers, or at least decision influencers. If you’ve had to struggle for several years using a badly designed bit of software from Company X, that had little or poorly written user assistance, then, later in life, when you get the chance, you’re going to make damned sure you don’t let  Company X inflict any more such pain on any of your staff!

It’s hard to come up with metrics to justify the current size of the docs team, beyond all argument. Bean counters are interested in having more beans to count, so winning new deals and satisfying contracts in order to be paid quickly are things that tend to impress them. In this regard, you could look at the number of documentation requirements within Request For Proposal documents from prospective customers, or you could find out whether documentation was scored as part of customer acceptance tests? 

But other than that, what can you come up with to use as proof of your value to the company that pays your wages? Well, the source of your wages may be the key, because really it’s your customers who pay your wages and they are the only ones who can provide metrics that will convince management of the value of what you’re doing.

I started this piece by suggesting that if you sack tech writers, or reduce the proportion of writers to developers, sooner or later customers will start to suffer. If that’s true then it should be measurable. Keep a record of the number of documentation-related support calls or bad customer feedback mentioned in engineer site visit reports. Have numbers gone up or down over the past six months?

You might never be able to prove that customers are happier because of the work you do, but if you’re able to prove that customers are less annoyed with the products and increasingly able to get on with their business without calling support, then you might just be able to convince people that documentation is valuable.

Madcap have, very sensibly, made it easy for you to add your own buttons to the toolbar of Flare’s WebHelp. You can use these custom buttons to … well, to do pretty much whatever you need them to do, within the power of JavaScript.

In this example, all the new button does is change the h1 heading style, giving it an orange background, but you could have buttons to completely change the whole look and feel of your WebHelp – to give readers some variety – or you could add a button that darkens the window and display a lightbox-style popup containing a video of you juggling cats. You might have more useful applications for this functionality, but you get the picture: the functionality is there for you to use however you want. The trick is how you add a button and then how you make that button call a JavaScript function. After that the rest is down to your own JavaScript/jQuery skills. 

So, the following assumes that each topic page in your WebHelp calls a JavaScript file where you keep all the cool, dynamic stuff you want to do when a reader clicks around in your help files. For example, I have a JavaScript file called MyWebHelp.js that uses a lot of jQuery to do stuff, so the head element of each HTML page in my help projects contains the following:

<script type="text/javascript" src="Resources/JavaScript/jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="Resources/JavaScript/MyWebHelp.js"></script>
        

To add a function button to the WebHelp toolbar
    

1. Create an image to serve as the toolbar button and save it as a .gif file.
   
   If you want the button to change on hover, or when clicked, then you can create 2 additional images for these states.
   
   These are the 3 images I used in this example:
   
        
2. In your JavaScript file add a function that you want to call when the toolbar button is clicked. For example, this function (using jQuery) adds an orange background to the h1 heading on the page (pretty useless, I know, but it illustrates the point):
   
   function makeHeadingOrange() { 
       $('h1').css('background-color','orange');
   }
3. From the Project Organizer in Flare, open the skin you want to modify.
4. Click the Styles tab.
5. Select Toolbar Item.
6. Right-click Toolbar Item and choose Add Class.
7. In the New Style dialog box, enter a name for your button class (for example, makeHeadingOrange).
   
   
8. Click OK.
9. Expand the Toolbar Item list and select your new class.
10. In the Basic properties for the class, click in the value column for Icon (this will currently be displaying “not set” as its value).
11. Click [Browse for image…] and find the button image you created.
    
    Notes:
    - When you specify an image it becomes part of the binary project data. The image file itself is not saved as a resource, like your screenshots, so you can only choose one of the existing images that have been absorbed into the project file, or incorporate a new image by browsing for it.
    - The images in this list are not sorted into alphabetical order. New images are simply added to the bottom of the list.
    
    
12. Choose images for the PressedIcon and HoverIcon properties (you can use the same image for all three states if you want).
13. Add a tooltip – for example, Make main heading orange.
14. In the Type properties for this class set ControlType to Button.
15. Set Onclick to the name of the function you want to call – in my example it’s makeHeadingOrange().
    
    
16. Click the WebHelp Toolbar tab.
    
    Your new button class is now shown in the Available list.
17. Move the button class into the Selected list and position as required using the up/down arrows.
    
    
18. In the section “Custom Javascript to include in Toolbar page”, click Edit.
19. Paste the following into the Toolbar JavaScript dialog box:
    
    function makeHeadingOrange() {
          parent.frames['body'].makeHeadingOrange();
    } 
    
    
    
    This creates a function called makeHeadingOrange which, when called, in turn calls another function called makeHeadingOrange. This second function is the one you added to your main JavaScript file in step 2 of this process. You could call them by different names if you wanted – but I think it’s clearer to call them the same thing. This second function is in a JavaScript file that’s referenced in your topic files and it isn’t directly accessible from the toolbar frame, so the first function (the one you added in Flare) is used to call it from within the context of the frame named “body”. The “body” frame in Flare WebHelp is the main frame within which the help topics are displayed. You could locate the code for the second JavaScript function within the topic HTML itself, but it’s going to be far easier if this function resides in a JavaScript file that you reference in the head of your topic pages.
    
    You can include as many custom Javascript functions as you want, listed one after the other in this dialog box. When the project is compiled, the text in this box becomes a file called Toolbar.js in the Data/<skin name>/ directory of your WebHelp output.
    
    So, if you want to, you can have lots of buttons, each calling a different function in your main JavaScript file (via the functions in the Toolbar.js file).
20. Click OK to close the Toolbar JavaScript dialog box.
21. Save your changes.
22. Build the WebHelp target output and test the results.
    
    Hovering over the button:
     
    
    Clicking the button:
     

My video camera records in 16:9, which has taken over from 4:3 as the standard aspect ratio. The trouble is, when I play those video in Windows Media Player, or try and edit them in something like Windows Movie Maker, they get displayed as 4:3. If I go and manually change the aspect ratio in the application, all that does is give me black bars right and left of the picture.

Searching for a solution, I found an explanation of what was happening, plus a very nice little free fixer tool here:

http://forums.cnet.com/5208-7594_102-0.html?threadID=308647

All Panasonic,JVC and Canon mpeg2 camcorders that generate MOD files on either HDD or SD-card do not set the widescreen flag in the mpeg2 sequence headers in 16:9 mode. Instead they leave it as 4:3 and put the information, whether 16:9 or 4:3 was used, inside the corresponding MOI file.
        Unfortunately most video player or editing software do not evaluate the content of the MOI file and therefore the video remains in 4:3.
        I have written a small tool sdcopy that can automatically correct the 16:9 flag of multiple MOD files. In addition, it can automatically copy all found MOD files(of all subfolders) into a single target folder. Sdcopy does not modify or decrease the video quality, it just patches the headers.
        You can download sdcopy from here, its freeware:
        http://zyvid.com/smf/index.php?action=dlattach;topic=280.0;id=218

 
I’ve used SDcopy and it did exactly what I wanted: produced videos that opened up in Media Player in 16:9 and, in the process, gave the files much more meaningful file names.

A little tip for users of Madcap Flare who find that things are getting very … very … very … s – l – o – w …

Your problem may be that the Flare database for your project has got messed up in some way. The symptoms of this are that you can be typing in the editor but no characters are showing up, then, after you wait a few seconds they appear, so you go on typing, but then things slow up again.

Flare uses a Microsoft SQL Server database to keep track of the interconnections between topics. This helps prevent you screwing things up when you delete a topic – because Flare will ask you what you want to do about all the references to that topic and will convert all the hyperlinks to normal text, if that’s what you want to do.

To repair a messed up database:

1. Save your work.
2. Close the project and Flare.
3. In Windows Explorer, go to the Analyzer subdirectory for the project.
   
   
4. Delete the files in this directory.
5. Restart Flare and load the project.
   
   Flare will rebuild the database. This will take a few minutes, depending on the size of the project – during which time you’ll see lots of activity in Flare’s status bar – but once it’s done you should have a nice speedy Flare again.

The other things you can do to speed up Flare a little are:

• Disable phrase collecting (choose Tools > Options > Analyzer and remove the selection from the check box). This turns off the phrase suggestions that you see in the Intellisense popups (if you have that turned on). If you don’t use this, turn it off.
• Turn off Intellisense all together (choose Edit > Intellisense and remove the selection of Enable Intellisense). Personally, I found this feature annoying rather than useful, so I prefer to have it turned off anyway. 

After several months away from Madcap Flare, coming back to work on it again, I’m reminded that one of the reasons I like this technical authoring tool is that it uses standard XHTML. So, if you’re using Flare to produce online help, you can modify your pages just like you could any Web page. So, for example, because I don’t like Flare’s default (text-only) glossary popups, I’ve replaced those with my own variety that allow text formatting and images, and can be dragged around the screen. And because I don’t have the budget for Madcap’s Feedback Server, I’ve hooked our help system up to a MySQL database, using AJAX and PHP, to give some of the same functionality. All good stuff and it’s great to have the freedom to do that kind of customisation.

And with formatting and styling it’s pretty much the same story. By using CSS, you have a high degree of control over the look and feel of your output. For example, I’m working on a WebHelp system right now and it’s been fairly straightforward to get most of the output looking more or less how I want it to look. The simple things like changing the background colours, the fonts, the icons, and so on are easily done from within the Flare application. And there are other things you can achieve by using Javascript to inject a CSS file dynamically on page load, if you want to override things in the Flare stylesheets that are injected into your output files at build time.

However, I’m painfully reminded, working with Flare again today, that one of the reasons I’m not 100% of a Flare fan is that Madcap fell short of making the styling of output 100% configurable via stylesheets.

Things like the Related Topics popups rely on Javascript, triggered by an onClick event, to add elements to the topic. This is perfectly standard, but whoever coded this decided in their wisdom to embed style information directly into those HTML elements, rather than giving everything a class name and controlling the styles from a stylesheet. In the hierarchical system that is CSS, nothing gets to overrule styles applied directly within the style attribute of an element in the HTML, so if the coder coded:

color="black"

then you you can have any colour you want, as long as it’s black – that is, you don’t get to modify the colour in your stylesheet to something more subtle, you’re stuck with the coder’s idea of what looks best for your output.

So my particular example today was that I was trying to beautify the Related Topics popup a little. Here’s what it looks like out of the box:

And I managed to modify most of it. But I just couldn’t get at that close button. It’s added directly by the Javascript. If it was in a Madcap CSS file – for example, as the background image on a div – then I could have overridden it with my own close button. But in the end I thought: sod it, if I can’t replace it I’ll just remove it. So here’s what I ended up with:

I know I’m biased, but I think it’s a big improvement. A little close button would have been nice, but I think most users know, or will quickly work out, that clicking away from the popup box makes it go away.

To style this up I used the following Javascript to add an override CSS file, which allows me to get at some of those hard-to-read Madcap styles:

$(document).ready(function(){
    ...
    //Append a link to the CSS file
    var newCSSlink=document.createElement('link');
    newCSSlink.setAttribute("href","Resources/StyleSheets/MCstylesOverrider.css");
    newCSSlink.setAttribute("rel","stylesheet");
    newCSSlink.setAttribute("type", "text/css");
    headElement = document.getElementsByTagName("head")[0];
    headElement.appendChild(newCSSlink);
    ...
});

This first line of the above code gives away that I’m using jQuery as an easy way to select and modify elements in the HTML. This just requires an extra Javascript file reference in the head of each page. If you use Javascript and you’re not familiar with jQuery, I’d strongly advise you have a look at it now!

Within my MCstylesOverrider.css file, the bit of CSS that removes the div containing the close button is:

div.MCKLinkBody div
{
    display: none;
}

Flare presents you with the old 80:20 rule. To get to a state where you’d be happy with the styling and behaviour of everything, you’d spend 20% of your time and effort getting 80% there, and then you’d spend the remaining 80% of the time finishing things off. For us pernickety perfectionists, Madcap could have made life a whole lot easier by making everything accessible and easy to change.

Message to software developers: when it comes to look and feel, less of the hard coding – please!