Surprising MS Word Functionality 29th January 2010 (Friday)
Posted by Colum McAndrew in Microsoft Office, Word.Tags: find and replace, Wildcard characters
5 comments
I recently came across an interesting scenario. A friend of mine was editing a Word document that contained lots of references to Carbon Dioxide but using its abbreviation, CO2. The problem he had was that the abbreviation was written throughout as “CO2”. Naturally he wanted to replace this with the “2” in subscript.
Occasions like this call for a find and replace tool. Word’s own find and replace tool should cope with this right? After all it is just replacing like with like. The problem was that on the face of it, it didn’t. The “Replace” in the dialog does not account for subscript text. You can specify the format of the replaced text, but this applies to entire text string. Therefore “CO2” becomes “CO2”. Not good at all.
It was after a few emails that an ingenious solution was found. Word’s find and replace tool allows you to specify wildcard characters in the replace string. What is more, it has one or two that you may not have come across before. How about “^c”. Believe it or not, this replaces your text string with whatever is currently located on your PC clipboard.
So all that remained to be done was create a piece of text complete with the required subscript formatting and copy this to the clipboard. Once there, you can perform your find and replace but using the “^c” replace string. Genius! As previously stated, this works with anything on the clipboard (e.g. images). If I discover anything else like this about Word I may have to take back everything I’ve ever said about it ;-)
Note: You can discover other find and replace wildcard treats by searching the online help.
I recently came across an interesting scenario. Another Technical Writer was editing a Word document that contained lots of references to Carbon Dioxide but using its abbreviation, CO2. The problem he had was that the abbreviation was written throughout as “CO2”. Naturally he wanted to replace this with the “2” in subscript.
Occasions like this call for a find and replace tool. Word’s own find and replace tool should cope with this right? After all it is just replacing like with like. The problem was that on the face of it, it didn’t. The “Replace” in the dialog does not account for subscript text. You can specify the format of the replaced text, but this applies to entire text string. Therefore “CO2” becomes “CO2”. Not good at all.
It was after a few emails that an ingenious solution was found. Word’s find and replace tool allows you to specify wildcard characters in the replace string. What is more, it has one or two that you may not have come across before. How about “^c”. Believe it or not, this replaces your text string with whatever is currently located on your PC clipboard.
So all that remained to be done was create a piece of text complete with the required subscript formatting and copy this to the clipboard. Once there, you can perform your find and replace but using the “^c” replace string. Genius! As previously stated, this works with anything on the clipboard (e.g. images).
If I discover anything else like this about Word I may have to take back everything I’ve ever said about it ;-)
“Extremely severe” weather? 6th January 2010 (Wednesday)
Posted by Colum McAndrew in Language, Technical Writing.4 comments
I must be getting Grammer Obsessive Disorder. Either that or just too pedantic. The touble is I’m starting to get really frustrated with the english people use where I may have let it pass me by in years gone by.
One such example is the UK weather forecasts of late. Ever since part of England was hit by some severe floods a couple of years ago I noticed the forecasters giving a “severe weather warning” whenever something untoward was predicted. To start with this was fine. After all if you are about to get hit by gale force winds you’ll want to everything in your garden is tied down.
The problem is that barely a day goes by without another “severe weather warning”. You’d think we were living in the Antarctic the way that they overplay the likely conditions. Is it just me or does heavy rain or 30mph winds contribute to something I need to take special care over? I think not. Sure if the roads are going to be icy in the morning you’ll want to take greater care on the drive to work but even a single half meter patch of ice within a single 10km radius seems to warrant a warning.
Of course all of these warning means the likes of me pay less attention to them than they probably should. It seems the Met Office has realised this and changed tack accordingly. Those of you in the UK will know we are going through a bit of a cold spell at the moment. Snow abounds and as our preparation for adverse weather is to mimic an Ostrich, this is one of those occasions where we need just such a warning. So in order to draw attention to the severity of the problem we now have “Extremely severe” weather warnings.
What next? Maybe, “Significantly intense acute excessive extreme severe”? I’m off the lie down in a darkened room ;-)
ISTC Communicator Journal: Standarding a Documentation Suite Pt.1 5th January 2010 (Tuesday)
Posted by Colum McAndrew in Technical Writing.1 comment so far
The winter 2009 edition of the Communicator journal published by the Institute of Scientific and Technical Communicator (ISTC) has an article by me on how we are standardising our documentation suite. The ISTC have kindly agreed to me hosting it online so that a wider audience can read it, so I have added it to my Acrobat.com account. Click here to either download (or preview) it. For context I have adde a brief background to the article below.
Since I started in my current position we have been trying to address the pain points in our documentation. These were varied, but centred on the following:
- A non-standard look and feel. A legacy meant different products being documented to the standards agreed by the Product Manager and with little agreement between them.
- Sufficient information to get a process completed but little consideration to why they needed to do it or what would happen when they did.
- Where a task fitted into the overall process and what users needed to do next.
- Providing a context for users to see where the process fitted into their job function.
The article is in two parts, with the second part being in the Spring 2010 issue.
A review of the Noughty’s – Part 1 30th December 2009 (Wednesday)
Posted by Colum McAndrew in Technical Writing.Tags: CHMs, FlashHelp, JavaHelp, Microsoft HTML Help, WebHelp
2 comments
David Farbey tweeted recently on how he had noticed how everyone had started summarising the years 2000 to 2009. As the end of a decade is such a momentous event (?) it is probably inevitable that editors struggling for a story during what is called “the silly season” turn to an easy fix. Not to be outdone, and honouring the fact that I have, officially at least, been a Technical Writer since 1999, I offer my own completely unscientific review of how the technical communication world has changed in the last ten years.
Note: I have split the review up into parts. Part One covers the migration from static offline help to user generated on line help.
Help….WinHelp!
In the good ol’ days when I had loads of money (pre-marriage) a full head of hair (also pre-marriage and pre-work) and technical communicators were easily pleased, I produced my first piece of documentation in WinHelp format. The sleek, familiar user interface made my first foray in technical writing a relative breeze. Oh how the mighty has fallen. One look at a WinHelp project these days makes me wince. OK there were some good things about it (e.g. non-scrolling regions) but on the whole it just doesn’t cut it in today’s feature rich, customer interaction environment. They just didn’t provide enough functionality for the discerning user and we Technical Writers just had to go. Whilst they are still used to this day, despite Microsoft’s best efforts, they are few and far between having largely been relegated to legacy help files for old and tired applications that have get to be sunset or assigned a budget to upgrade.
The step to Microsoft HTML Help brought with it a rich stream of possibilities to improve user content. Like anything new it required a certain amount of getting used to, not least the fact that it was coded using HTML, but on the whole it was a huge step forward. Just the fact that you weren’t using MS Word as your editor was surely reason enough to change. However rather ironically a number of Help Authoring Tools surfaced that allowed you to generate the required HTML from a MS Word like interface. Now you could produce HTML in from a familiar interface without the vagaries of the familiar application! All of a sudden you could produce your HTML code without ever coding anything. Whilst it is possible to create your HTML topics in Notepad (I know someone who does even now) tools like Adobe RoboHelp provided an MS Word like user interface with which to produce your works of art. Microsoft HTML Help also brought with it a range of new gadgets and tools that allowed you to enrich your content (e.g. DHTML, browse sequences, forms, etc.).
However arguably even Microsoft HTML Help has its day. Whilst CHM files are still widely used and probably will be for sometime to come, the arrival of the Internet brought with it the need for online content. With the concept of a CHM being that they are designed to run on a local PC, we often used to see if we could bend the rules by placing them online. This worked to a degree but the incessant need for 100% security soon drove a dagger into any CHM file located online. They were deemed to be a risk and after Microsoft released Security Update 896358 in June 2005 they could no longer be effective unless located on a local drive.
Online help became the buzzword of the day. Outputs like WebHelp and FlashHelp gave Technical Writers the ability to change from being purely content providers to someone who could start to change the look and feel of the documentation we provided. The advent of skins allowed us to design the interface to the documentation as well as the documentation itself. What is more these outputs were more flexible allowing us to place them on internal intranets or an external site. Now our users could access the very latest documentation without having to install or upgrade an application. What is more, they could do so from anywhere provided they had an internet connection. All of a sudden staff in the field became enabled to find information quickly and easily.
Now I can’t let a review of output formats of the last ten years go by without mentioning my nemesis. For a short period after taking on my current position I was tasked with producing JavaHelp. The misguided decision made before I joined that this was the required output type because our application was written in Java was soon reversed! As soon as I pointed out the long list of its limitations and more importantly the negative feedback we were getting from users, particularly around searching, we managed to get agreement to change. If anything, it was this decision that highlights the changes that have occurred throughout my career. Namely that the documentation function has gone from something that costs, to something that can add real value to the product. The powers to be can see that it eases pressure points and can be a real difference to the overall user experience.
Mind expanding HTML 24th December 2009 (Thursday)
Posted by Colum McAndrew in RoboHelp.Tags: Expansions, HTML, tags
4 comments
I know quite a few RoboHelp users go into apoplexy when faced with going into the HTML created by the WYSIWYG but sometimes you just have to get down and dirty. When you do, it’s likely to solve an issue with the way the WYSIWYG is displaying the source or to add or amend content (e.g. Meta tag, JavaScript, etc.). In these scenarios you are tinkering with the existing HTML code rather than writing it from scratch.
Should you wish to create your own HTML rather than using the WYSIWYG, you’ll find a very useful feature inside the HTML editor. The Expansions feature allows the editor to predict what HTML tag you require and lets you auto complete them when you are happy it has found the right one. The functionality includes a number of standard tags but you can edit these to add additional tags to meet your needs.
To tell whether the Expansions functionality is on, right click anywhere in the HTML editor. A popup menu is displayed which contains the Expansions menu item. The menu item toggles the functionality on and off with a tick placed before it if it is on. The popup menu also has an Edit Expansions menu item that gives you the opportunity to create your own HTML tags, although this is only available if Expansions are turned on.
So let’s say we want to add a paragraph tag to the HTML. As soon as you type the opening tag bracket (<) the Expansions functionality kicks in and a popup dialog is displayed with the list of expansion matches displayed. If you then type a “P” the paragraph tag is found allowing you to press Enter to auto complete the tag.
| For example:
|
Results in:
|
The only issue I have with this functionality is that after adding the expansion the cursor is placed after the closing tag. This means you have to go back to edit the actual text inside the tag. Whilst the text that is added can be changed by editing the expansion (see below) this does make the process slower and therefore less useful. Personally I’d have preferred if the Expansions functionality only added the appropriate opening or closing tag, not both. I have managed to get around this by deleting the expansions I use on a regular basis and replacing them with two separate versions; one to open (e.g. <p>) and the other to close (e.g. </p>). This makes editing easier by adding tags as and when you need them without the need to go back and reedit text.
Adding an Expansion is easy. Use the Edit Expansions menu item and in the dialog click New. Enter a keyword, caption and text and press OK. The text you enter is the actual HTML code that is entered in the source.
Technical Communication Suite Keyboard Shortcuts 23rd November 2009 (Monday)
Posted by Colum McAndrew in Acrobat Professional, Adobe, Captivate, FrameMaker, RoboHelp, Technical Communication Suite.4 comments
I know that they are not everyone’s cup of tea but give me a keyboard shortcut any day over a mouse click. Maybe it’s an author thing but if I am typing anyway, why move your hands away from the keyboard to do something. Provided it doesn’t require a form of digit dexterity only found in aspiring Houdini impersonators, sock it to me.
When it comes to the various packages in Abobe’s Technical Communication Suite the keyboard shortcuts are well documented just not all in the help. I’ve seen various posts in the past detailing the shortcuts for one or other of the suite’s packages but not for all. That is until now. Kevin Speigal’s, co-founder of Icon Logic, has written helpful features on his blog listing all the keyboard shortcuts for each of the main four applications that make up the Technical Communication Suite. Check them out.
Help documentation on Channel 85! 19th November 2009 (Thursday)
Posted by Colum McAndrew in Captivate, Technical Writing.7 comments
Anyone who knows me well will tell you, I am a big football fan. No not the “football” where the ball only rarely touches a player’s foot (well OK I am a fan of it) but the European and more accurately named variety ;-) My team, AFC Wimbledon, will need no introduction to true football (soccer) fans as its model is based on a club owned and run by the fans. Just like FC Barcelona except without the bulging trophy cabinet and multi-million pound turnover!
As a regular contributor to various club fanzines I was struck but a comment made by another contributor and AFC Wimbledon fan, Ian McNay. Ian is Chair of Cherry Red Records, a record company based in the United Kingdom. He recently set up a TV station for the club that features game highlights, interviews with key club figures and post match analysis. However really caught my eye was his vision for the future. He says, “Within a few years all decent websites will be mini television stations.”
This got my thinking of the other part of my life that is not devoted to football reporting. Could not the same be said of documentation? Especially as I was sent a Tweet recently suggesting that I embed occasional Captivate movies in this blog. Excellent idea I thought, and follows on from my day job where my team has recorded and embedded Captivate files inside the help. It has proved a real vote winner internally and will surely have a similarly positive response once our user base gets hold of it.
It is a vision at our company to change the overall user experience of using our product documentation. Gone are the days when we produced flat, dry manuals and help files. We are moving to a much greater level of interaction. The first step of which is the Captivate movies inside the help documentation that is itself hosted online. This has the added benefit that we can email users the URL to specific help topics to help solve their queries when they contact us. We have a LinkedIn User group for customers to discuss more general application issues. We also plan to have other internal product forums for a more immediate response.
The documentation though is a real area of interest for me. My experience of using help files is that they often only go so far. They are written with a specific audience in mind and normally have to be fairly generic by nature. As such they may tell me how to do something but not how I could use that knowledge to make better use of the software. Wouldn’t it be great if the help could also be a living, breathing documentation source where users can add links to blogs, wikis, websites and the like that would add to the overall user experience.
Adobe is already doing this with the Adobe Air applications built into their applications. You can add comments to a help topic that once approved appear for all and sundry to see. Just imagine the power of a help file if it not only told you how to do something, but also contained links to useful resources demonstrating how others were using it. There really is no end to the possibilities that such functionality offers. Adobe is working on full integration with Adobe Air in RoboHelp and other products, and I for one can’t wait.
So the aim is a help file that acts as a portal to other useful information. As a Technical Writer my role will change. A television presenter I may not be but having the responsibility for being a moderator of a truly interactive, useful help environment? I could do that.
Alphabetti Spaghetti 18th November 2009 (Wednesday)
Posted by Colum McAndrew in Adobe, RoboHelp.3 comments
A short while ago, the question was asked on the RoboHelp forums how to organise snippets so that they appeared in alphabetical order. This should not be a problem for you if you don’t have many snippets or are using RoboHelp 8. If, like me, you only have 4-5 snippets in any one project, whether they are displayed alphabetically is neither here nor there as the pod is way big enough to display them and they are easy to find.
Likewise users of RoboHelp 8 will know that snippets are automatically sorted alphabetically. It looks like users of RoboHelp 7 however do not have this functionality. So if you are on this version and use snippets in a big way, I can see how having to hunt through a list to find the one you want would be problematic.
You can of course manually sort your snippets inside their pod. Just right click on a snippet to display a popup menu from which you can move an item up or down one position in the snippet list. Trouble is, you have to repeat this over and over if the snippet needs to be moved more than one position. Also if you have lots of snippets this can lead to a lot of frustration to get things just the way you want. There has to be an easier way.
Thanks to the RoboWizzard, Rick Stone, who uncovered exactly where RoboHelp 7 stored the snippet information, there is. The answer lies in the Windows registry. Of course there are risks with doing anything with this so be warned. Don’t do anything in the registry without taking a backup and being 100% sure you know what you are doing. If you look in the HKEY_CURRENT_USER\Software\Adobe\RoboHTML\7.00\Components\36 location you should find a set of keys that map to your RoboHelp projects. If you click on a project, you will see the snippets used inside it. You can rearrange them by changing their name to something like Name0, Name1, Name2, etc.
BTW for the benefit of those outside the UK who may be wondering where Alphabetti Spaghetti in the title comes from, it was (and indeed may still be?) a food targeted at the young generation and students! Based on tins of baked beans, it was little pieces of spaghetti shaped in the shapes of the alphabet in tomato sauce. Trouble was, you used to spend so long arranging the damn things around your plate to spell words that by the time you ate them they were cold!
Definition of “Average” 17th November 2009 (Tuesday)
Posted by Colum McAndrew in Language.5 comments
I’ve been working of late with some documentation related to equations used by an analytical software package. Cue lots of mathematical symbols. Brain ache! During this exercise in torture I came across the following definition for the mathematical function otherwise known as Average:
“A representative figure that is used to give some impression of the size of all the items in a given population. This is a measure of central tendency. By this we mean that while a population may range in values, these values will be distributed around a central point. This central point is therefore in some way representative of the population as a whole. Averages are also known as measures of location, because they show roughly where data are located on a scale of values.”
Technically accurate but so far off the scale of use of succinct language LOL! Now what is the website of the Plain English Society?
Viewing WebHelp Pro & FlashHelp Pro output in RoboHelp 13th November 2009 (Friday)
Posted by Colum McAndrew in Adobe, RoboHelp, RoboHelp Server.add a comment
One of the minor irritations of using WebHelp Pro or FlashHelp Pro outputs from a RoboHelp project used to be the workflow you had to run through to check the output as it appears on the server. Once you had published your output to the server, you had to open a browser and type in the URL of the Web Administrator. Only then could you logon and display the project.
All of this has changed with the arrival of RoboHelp 8. This version has a RoboHelp Server pod that can be displayed via the View > Pods menu item. When the pod is first displayed, a “Setup” button is displayed which when clicked allows you to enter the path and name of the RoboHelp Server. Once set, a “Connect Now” button allows you to view the project’s published output.
Tip:
It is a good idea to size the pod to a size that comfortably displays the Web Administrator dialog and save your environment via the File > Environment > Save Environment menu item. If you don’t do this, you’ll have to manually resize the pod each time it is opened.
Grammar Obsessive Disorder 12th November 2009 (Thursday)
Posted by Colum McAndrew in Language.1 comment so far
My goodness. Do I really suffer from Grammar Obsessive Disorder? Check this out. It had me in tears. LOL!
Top 10 Technical Writer annoyances 12th November 2009 (Thursday)
Posted by Colum McAndrew in Technical Writing.Tags: Annoyances
18 comments
The life of a Technical Writer is far from boring. Days spent typing away at a keyboard are often disturbed by the rigours of the corporate world. I was reminded of this earlier today when one of my team, a relatively new recruit to the world of technical authoring, discovered that occasionally being kept in the dark can be annoying. In honour of this momentous occasion, I offer to you for your delectation my own top ten ways to annoy a Technical Author.
- Get them to produce a documentation product estimate based on functional specification with statements that contain “It is likely that this may change”.
- Add, remove or change the fields on a dialog after it has been documented and not tell you.
- Remove a large area of functionality you have spent weeks documenting on the day of the deadline for the final product build.
- Write a functional specification that mirrors a conscious brain dump of information with little or no logical structure.
- Ask them to make a “minor” change to a document whilst singularly failing to realise the implications of such an action.
- Ask them to produce an online version of a paper document and give them the paper document.
- Complain that there is no documentation without even looking.
- Ask them to produce a document, then never approve it and ask for the same thing a few months later.
- Give them a typing test during their job interview! After all that’s all they really need to know.
- Tell them Microsoft Word should be plenty to produce user documentation.
Welcome to the world of technical authoring.
Note: My thanks to Laurin Marden (follow her on twitter – @lmardennh) for the inspiration, and some of the content, for this post.
