Category Archives: Technical Writing

Leveraging jQuery scripts and CSS3 in your Online Help #techcomm

I often get frustrated when people ask in technical communication forums and email lists what are the “current trends in help”. Why limit help to such a small, self-enclosed space, when we have an incredible wealth of knowledge that is current and also contains what users want: the Web.

There’s really no reason that help has to look like traditional “help”, and not like a web site, especially since framesets, the “technology” that creates the tri-pane TOC/content/navigation most help authors are familiar with, went out of style in, oh, 1999. MadCap is finally taking the lead here with frameset-less output, though I suspect Adobe’s RoboHelp isn’t far behind.

Continue reading Leveraging jQuery scripts and CSS3 in your Online Help #techcomm

How to Embed Fonts in MadCap Flare WebHelp

This story is for intermediate to advanced help developers. It requires knowledge of HTML, CSS, and a help authoring tool such as MadCap Flare or Adobe Robohelp.

Have you ever been bored using Georgia, Tahoma, Verdana, and (sigh…) Arial over and over in your help projects? The font-face property has been available for some time in Cascading Style Sheets (CSS), but browser and font foundry support are only now allowing use of fonts other than those that ship with operating systems and applications, without workarounds like sIFR and cufon.

New technologies have sprouted up, with Google creating its own font API, and Adobe announcing font support through TypeKit. However, you can also save and host freely available font files on your company’s web server, or install on your users’ PCs, and use these fonts in your WebHelp projects. The web site Font Squirrel creates the CSS for you, using only free, embeddable fonts.

There are thousands of free fonts out there, but not all font creators support font embedding, so be sure to read any license agreement before using them in your projects.

MadCap’s Flare help authoring tool (HAT) uses CSS to style its WebHelp, so you can easily  embed fonts into your help. This should work similarly in Adobe Robohelp. Continue reading How to Embed Fonts in MadCap Flare WebHelp

Deconstructing a Twitter Post

When I meet Facebook friends in real life (yes, that actually happens…), they almost always tell me they can’t understand my status updates. That’s typically because my status updates are almost always my Twitter updates. I have Facebook set to read my twitter feed, and update my status to reflect it. This is primarily a result of work blocking Facebook, but also because it was annoying to have to update things in two places. Twitter’s also as easy as sending a text message from my dumbphone.
As I retweeted the following message, it struck me as a perfect opportunity to educate the masses.
she deserves it! //RT @scoop42: Simona de Silvestro a 4-x winner in Atlantic Championship will test HVM #IndyCar on the 8th &9th in Sebring.
Like everything else, there are a million possible ways to do this. This is one way, that I see in the majority of posts. Let’s deconstruct it:

  • she deserves it! – this is my reply to the original post, or tweet.
  • // – a divider between my thoughts and the original tweet.
  • RT- retweet. It announces that I am resending, or echoing what someone previously tweeted. This is changing with the new Twitter retweeting thing, which i really don’t like on Tweetdeck.
  • @scoop42 – The original poster. User scoop42 is a reporter for ESPN. He wrote that Simona de Silvestro has an Indycar test in Sebring, Florida for the HVM team on December 8th and 9th.

As an aside, she totally deserves the test. I saw her drive twice in Atlantics at NJ and Lime Rock, and the girl has talent. I hope she does well.

So there you have it, a tweet post in a nutshell. Now, time to make dinner… but that’s another post.

Tips for working with Web Designers

A friend contacted me on Facebook to ask if I knew any web site designers for her sister’s newly-opened store. I replied with this, which is probably way more than she asked for. Then I realized I could repurpose the content. I think they’re good tips for anyone looking to find someone to create and maintain their web site.

  • Depending on your business, there could be niche designers. I know there are designers who work solely with race car drivers and teams, or restaurants, so that may be something to look into.
  • Before you talk or meet with anyone, find some of your competition’s sites, see what features they have, list what you like and dislike. Do the same thing with sites you visit regularly. Ask yourself if you are one of those people who hated Facebook’s re-redesign. Why? Why not?
  • Don’t walk into any conversation with “I’m not really tech-y, but…”. You’re already giving them the upper hand.
  • “Web 2.0” doesn’t mean all that much.
  • Make sure they respond to emails within a reasonable amount of time, especially if it’s the only way you communicate.
  • Don’t trust anyone who tells you they can get your site in the top 10 on google. Don’t listen to anyone who is a search engine optimization (SEO) expert. SEO simply doesn’t work, and in some cases will get you worse results than if you haven’t done anything.
  • Make sure you see an online portfolio, and that you like what you see.
  • Navigation and search are extraordinarily important; make sure they work on the sites in their portfolio you visit, and are logical.
  • Don’t use the lowest bidder, but don’t necessarily use the highest either. Pay for experience.
  • In this economy, tons of designers are looking for work. Make sure you like them and are someone with whom you can see yourself having a long working relationship.
  • Give them as much clean, grammatically correct text as you can. Remember, designers generally aren’t writers or editors. They take what they’re given and put it on the page.
  • Make sure you give value back to the customer. Maybe start a blog about your sister’s area of expertise, and make sure it’s updated regularly.
  • Keep the site fresh, too; just like with a designer, you want to start a long relationship with the people who visit your site. You can’t make it look like no one’s minding the virtual store, or no one will come back to check after awhile.
  • Listen to people who talk about content management, content management systems, or CMS. If they use words like Drupal, Joomla, or WordPress (all great CMS), make sure they explain it to you. Ask questions.
  • And remember – it’s not just a page anymore. You can’t just slip some nice graphics on a page and a little bit of vague sales-y text. We call that ‘brochureware’. It’s a site.

What Adobe Should Put in Framemaker 10

If you’re fortunate enough not to use Word, it seems the only other decent choice for technical writing is Adobe’s Framemaker. However, some of Frame’s quirks make Word look almost welcoming. Here’s a running list of the things I’d like to see in the next release of Frame, in no particular order:

  • Find and Replace with more functions. How come I can find a marker, but can’t replace it with a different kind of marker?
  • Dialog boxes and palettes that you can close with the Esc key.
  • More intuitive keyboard shortcuts. All of these Esc functions hearken back to UNIX, and when’s the last time anyone used Frame on UNIX?
  • Drag and drop text. C’mon, this was a new feature to users back in, what, 1990?
  • I can’t believe I’m writing this, but Macintosh support. Seriously, I’d give the Mac another look if Frame ran on it natively. Emulation doesn’t count. Yes, I’m aware of Boot Camp and Parallels.
  • Full OpenType support. All of Adobe’s fonts are now OpenType, with ligatures and special characters, but yet we tech writers get the typographical shaft.
  • Word processing features, like AutoCorrect, spellcheck as you type, and all of those everyday functions that Word has, but writing in Word is so bad that you refuse to go back.
  • How about Ctrl-backspace to delete a word before the cursor, just as Ctrl-delete works great for deleting the word before a cursor. Again, this was a feature of, let’s say, Word 2.0?
  • Support for transparent PNGs.
  • How about a more usable “missing file” dialog box? If you type in the path to the file, Frame doesn’t change to that directory, it accepts that as the filename!
  • Much better style management. How come I can import styles across a book, but they don’t always update? Why can’t I delete unused styles? Argh.
  • A reasonable upgrade price commensurate with the new features. All DITA, all the time, isn’t worth $400.

Check back often for updates to this list, since I find something that drives me insane pretty regularly.

Powered by ScribeFire.