Category: Technical Writing

Posted on

Technical Communications: Small Steps to a Giant Leap…

by Tony Self Follow us on Twitter View our profile on LinkedIn
 
Neil Armstrong, the first person to walk on the Moon, was born just twenty-eight years after Charles Lindbergh, who was the first person to fly non-stop across the Atlantic Ocean. In just one human generation, technology had progressed from fabric covered craft (with a speed of 130 mph and a range of 4,000 miles) to a liquid oxygen powered rocket ship that traveled at speeds of up to 25,000 mph (on a trip that covered 500,000 miles).

Technological change is not new, but the pace of change in some fields is breathtaking. Battery technology is one example, and photo-voltaics is another. And of course, technology associated with reading is experiencing a dramatic rate of change.

How do people cope with rapid change in their fields? Neil Armstrong learned to fly in 1945… a time when the sound barrier was considered to be an impenetrable barrier. By the time of Armstrong's first posting as a US Navy pilot in 1950, the sound barrier had been broken, and the first jet fighter squadrons had been formed. In 1957, Armstrong flew a rocket-powered aircraft for the first time. By 1960 he had flown at close to 4,000 mph (six times the speed of sound) to heights of 120,000 feet. Armstrong managed this transition as a pilot by continually learning. Over 10 years, he progressed from subsonic jets, to transonic jets, to supersonic jets, to rocket aircraft. Each step was relatively small, but overall it was a giant leap (to quote a phrase Armstrong later used when he stepped from Apollo 11).

How does Neil Armstrong's journey into space relate to technical communication? Consider that it only took 10 years for us to move from typewriters (1980) to laser printers (1990), from text-only Web browsers (1993) to websites with embedded movies (2003).

The Apollo 11 story can provide another lesson for technical communicators. As the name implies, Armstrong's Apollo 11 mission was the eleventh in a program of 20 missions. The program objective was landing a man on the Moon and returning him safely to the Earth. Each mission was part of a broad strategy… part of a far-sighted plan.

Big projects only reach their goals if they come with a comprehensive plan. Like many projects, there can be hurdles and disasters. The Apollo 1 spacecraft exploded on the launch pad, killing the three astronauts. The next three missions were unmanned flights to test systems. Each mission validated a different system. The unmanned Apollo 5 orbited the earth. Apollo 6 tested the Saturn V propulsion. Apollo 7 was a manned orbit. Apollo 8 circumnavigated the moon. Apollo 9 tested the lunar module, and 10 was a dress rehearsal. In documentation, this might be called iterative development. Unit testing is another IT term that might apply.

For large documentation or training projects, an Apollo approach is a good model. Here are some small steps to success:

  • Meticulously plan
  • Set achievable budgets and deadlines
  • Clearly state business goals
  • Develop a content strategy
  • Create prototypes and proof-of-concepts
  • Test and choose the right tools
  • Keep learning
  • Encourage your team
  • Continually check progress against the plan

and… most important…

  • Think big

Looking back, you'll see how those small steps became a giant leap.

Posted on

Technical Communications: Online Versus Paper

by Tony Self Follow us on Twitter View our profile on LinkedIn

What is more effective, a print document or an online document? It wasn't all that long ago that print documents would definitely have been voted more effective, especially considering the poor quality of computer monitors and slow internet speeds. (Remember trying to pull up a document on a modem?)

Given the speed of today's internet and mobile device support, print documents are likely going the way of the dinosaur. Online documents have several advantages to their print counterparts. For instance, eBooks reflow to fit the user's device (think about how popular eBook readers such as the Amazon Kindle have become in just the past few years). Online documents are searchable, typically contain hyperlinks for easy navigation, often include videos and/or animations, and some even contain interactivity in the form of eLearning simulations created in Adobe Captivate or Articulate Storyline.

There are millions upon millions of print documents around the business world that would gain new life if they were online. The major challenge in moving from unstructured to structured documentation, or page layout to reflowing text, or paper to online, is the shift in mindset required. Simply put, many old design paradigms used for print documents don't fit in new media design.

There are many reasons for converting paper documents to online documents such as cost, efficiency of updating, document control, accessibility, and discoverability. Surprisingly, for the custodians of paper documents charged with managing the conversion, there is often a reluctance to embrace the migration from print to online. For those custodians, the paper version remains the primary document, and the online version is secondary. 

Even if the paper custodians agree to take the paper documents online, much time and effort is spent trying to imitate the paper design in the online design. For example, the paper documents are scanned and converted to PDF. While aPDF will work in an online world, a PDF is really just a digital replica of the paper document. While a PDF may open on a tablet or smartphone, it won't re-flow to fit the user's screen like an eBook.

If you're trying to convince the "powers that be" to make the move from print documentation to an online document, consider the following:

The text used in the print document may require a specific font and font size. When online content is displayed for the user, the user's device may have limited font capabilities. Even if the device is capable of displaying the font, if the user doesn't have that specific font installed on the device, the font displayed will be the browser's default. For instance, you have used Futura as the font for your content. If the user accesses your content via a web browser and does not have the Futura font on their computer, the browser will likely display Times New Roman instead.

Paragraphs may need to be indented by a specific amount. While setting up a specific indentation is easy in a print layout tool such as Adobe InDesign, the user's device may have limits to how indentations are displayed.

Headings may have to be sequentially numbered. While many print layout tools allow you to easily number paragraphs, those automatic numbers may not display properly online.

You may be required to include footnotes. While footnotes are easy to add to print documents, they're a problem online. Since there really isn't an end to a page online, where would the footnotes go?

Page numbers may no longer be valid. If your print document includes cross references (such as, "For more information, see page 11"), you could end up with a mess. If your print content is displayed as an eBook, the content that was on page 11 could now be located on page 22. If the text on the page tells the user to reference page 11, but the text is actually on page 22, you can imagine the trouble you'll have.

The graphics could be huge. In the print document, high resolution photos were used. They look great on paper. However, they're so big (in megabytes, not width or height), they'll take forever to download over the Internet if you leave them as-is. To use the images, you'll need to allow time to save the images as online versions (in jpeg or png format). When you do, the images will likely lose quality. Will they still look good?

If you do decide to migrate your print documents to the online world, off-the-shelf authoring tools such as Adobe RoboHelp and MadCap Flare will help make the process easy. Both tools allow you to quickly convert printed documentation (especially Word documents) into online documents. Both tools support cascading style sheets that handle fonts, colors, paragraph numbering, and indentation. And both tools allow you to create master pages complete with headers and footers. Nevertheless, there are limits to what any authoring tool can do when it comes to recreating the look and feel of a print document, so look into the limitations of each tool prior to moving forward. 

What's your take on print documents as compared to online documents? Is print doomed? Which medium do you think is more effective, print or online? What tool do you use to convert from print to online? Can you share instances/examples where you think print documents are more effective than online documents? Feel free to post your opinion as comments below.

Posted on

Adobe FrameMaker: On-Demand QR Codes

by Kevin Siegel Follow us on Twitter View our profile on LinkedIn View our videos on YouTube

Unless you've been deliberately avoiding them, it's a good bet you've come across images similar to the one below.

QR Code leading to the IconLogic website. 
 
The image is known as a QR code. As you can see, QR codes are images that are made up of black and white squares. They are typically used for storing URLs or other information and can be scanned by QR Readers. In fact, if you have a smart phone, it may already have a QR Scanner. If so, scan the image above with the QR Reader and you'll be taken to the IconLogic website.
 
There's plenty of software you can find on the Internet that will allow you to create your own QR codes (some are free; some will cost you a few bucks). However, if you own Adobe FrameMaker 12, you have that ability to create QR Codes right now.
  1. Open or create a FrameMaker document and click where you want the QR code.
  2. Choose Special > Generate QR Code to open the QR Code Builder.
  3. In the File Name field, give the QR code a name (it will be saved as a PNG image) and specify a storage location.
    Adobe FrameMaker: Naming a QR Code.
  4. From the Type drop-down menu, select the type of QR Code you'd like to create (you can select from SMS, URL, Phone, Email, and Text).
    Adobe FrameMaker: QR Code type
  5. In the image below, I selected URL from the Type drop-down menu and then typed the IconLogic website URL.
    Adobe FrameMaker: URL QR Code.
  6. The final step is to set the size of the URL from the Size drop-down menu. (You can select a size from the Image Dimensions drop-down menu or type your own value into the Image Dimensions field.)
    Adobe FrameMaker: QR Codes
  7. Click the Insert button to insert the QR Code into the FrameMaker document.
And that's that. If you only wanted to use the QR Code in your FrameMaker document, you're done. However, if you want to use the QR Code in a different program, or include it in a newsletter like I did above, you'll find the QR Code image file in the folder you specified when you named the image (see step 3 above).

 

***

Looking for instructor-led training on Adobe FrameMaker? Check out our live, online, instructor-led FrameMaker classes.

Posted on

Adobe RoboHelp: Show Variables in Topics

by Willam Van Weelden Follow us on Twitter View our profile on LinkedIn

In previous articles you've learned about RoboHelp's User Defined Variables (how to create them, group them, and use them in topic titles).

As a brief review, variables can contain information that occurs frequently in your project, such as a product name, company name, or copyright notice. After creating the variable, you can insert it into any RoboHelp topic or onto a template by simply dragging and dropping. Now here's the cool part. Assume your company name now appears throughout your project and now you want to change it. Without the variable, you would have to search your entire project and update the company name. Thanks to variables, all you will need to do is update the definition of the CompanyName variable, and you will change the displayed company name project-wide in just a few seconds.

One issue you'll come across when inserting variables within a topic is that, by default, the variable text looks like regular topic text. In the picture below, I challenge you to locate the variable. 

Adobe RoboHelp: Find the variable text  

Did you find the variable text? I'm betting that the answer is no. So what's the big deal? This can be particularly frustrating if you need to replace regular text with a variable. For example, you can highlight regular text in a topic and convert it to a variable by dragging the variable on top of the text. That's an awesome feature. Before I begin however, I need to be able to tell, at a glance, if the text I'm looking to replace is already a variable. As it stands, I have no idea since I cannot tell the difference between a variable and regular text.

Luckily, RoboHelp has a handy feature that allows you to distinguish between variables and regular text in topics. To enable this feature, simply choose View > Show > Fields.

Adobe RoboHelp: Color coding for Variable Text. 

Voila. All variables in topics are now shown as green text. Best of all, variables only show up green in your project… when you generate a layout, the green color will not be visible to your users.

***

Looking for instructor-led training on RoboHelp? We offer live, online training once each month. We can also bring the same great training onsite to your facility. Interested? Contact us for details.
Posted on

Localization: Training and Development in Ecuador

by Jen Weaver Follow us on Twitter View our profile on LinkedIn

¡Hola! Let's journey down to South America and explore some common cultural facts about Ecuadorians and their expectations when it comes to training and development. 

Test Your Knowledge of Ecuadorian Culture:

  1. True or False. Ecuador is South America's second largest producer of oil.
  2. What is the official language of Ecuador?
  3. What currency is used in Ecuador?

 Tips for Training & Development in Ecuador1

  • Don't discuss other Spanish-speaking countries with Ecuadorians. Ecuador lost half its land to Peru in 1941 in an invasion supported by the United States, Argentina, and Brazil. Ecuador was previously conquered by Spain and has also faced many border disputes with Colombia. Similarly, be careful not to exhibit a sense of American superiority, as many Ecuadorians are sensitive to this attitude.
  • Ecuadorians tend to make decisions on a case-by-case basis rather than using universal laws or standards to guide behavior. Accordingly, an individual's faith or personal feelings may be viewed as "truth" independent of facts or data. Research alone will not gain buy-in from Ecuadorian learners; you must engage them on an ideological or emotional level.
  • Family gives Ecuadorians a sense of stability, but personal achievement and individual status are more important than the success of a group as a whole.
  • Despite government efforts to promote punctuality, most Ecuadorians view arriving 15 to 20 minutes late as still being on time. As a foreigner, you are expected to be prompt to all business meetings.
  • At the executive level, many business professionals arrive at the office after 9:00 a.m. Keep this in mind and avoid scheduling meetings or classes before 10:00 a.m., if possible.
  • Address Ecuadorian contacts by their professional title or formal name until invited to do otherwise.
  • Ecuadorian time is the same as Eastern Standard Time, so if you're traveling there from the United States, you may be tempted to schedule meetings the same day that you arrive. However, allow yourself at least a day to acclimate if training on location in Quito–not for the time difference but for the high altitude.

Trivia Answers:

  1. True.
  2. Spanish. English is commonly used in business settings, plus there are many indigenous languages still used by the Amerindian population. Be sure to clarify the language needs of your audience before finalizing training materials.
  3. The United States Dollar.

References:

1Morrison, Terri, & Conaway, Wayne A. (2006). Kiss, bow, or shake hands (2nd ed.). Avon: Adams Media.
 
***

Developing international training and development materials? Contact Jen at Carmazzi Global Solutions.

Posted on

User Assistance: Standard Gauge

by Tony Self Follow us on Twitter View our profile on LinkedIn

It doesn't quite sound believable, but it's true. In 21st Century Australia, there isn't a standard national rail gauge. (Gauge is the gap between railway tracks.) In some states, narrow gauge is used, in others broad gauge, and ironically in just one state, standard gauge. This means that rail cars and locomotives can't travel between states.

This schmozzle started in 1847, before the independent colonies of the Australia continent became states in a federated nation in 1901. It was in 1847 that the first railway lines (in South Australia) were built. It started well, with a decision by the British Government's Secretary of State for the Colonies that all colonies should adopt standard gauge.

But what does this obscure historical anecdote have to do with technical communication? Let's think standards, and how standard adoption by an industry can go horribly wrong with enormous, long-term financial consequences.

A private company building a railway line in New South Wales lobbied for the standard to be changed to broad gauge. Broad gauge became the new standard in 1854. A year later, the chief rail track engineer in New South Wales was replaced, and the new chief convinced the New South Wales government to unilaterally change the NSW "standard" back to standard gauge. And the same pattern continued until there was no standard left.

You may be awestruck by these decisions, but in context, having a standard made little difference. Australia is a big continent, and the mooted railway lines were short and were contained well within the colony. There were no plans for railway lines to cross borders, so as long as all lines within a colony used the same gauge, there would be no problem.

There are many standards in technical communication, and their adoption is haphazard and parochial, to put it kindly.ISO/IEC 82079 is an international standard for technical communication, covering all types of product, software, and service related instructions for use. ISO/IEC 26514 provides requirements for the design and development of software user documentation. Both these standards arouse very little discussion in online forums or at technical communication conferences.

The Organization for the Advancement of Structured Information Standards, OASIS, approved the DITA standard in 2005, and although its adoption is growing, it is still nowhere near widespread in technical communication. Are technical communicators generally reluctant to adopt standards? It is undeniable that technical communicators love some standards, such as spelling and grammar, and argue strongly for the benefits of such language standards and conventions. But it seems to me that beyond language standards, we collectively show the same attitudes as the late 19th century colonial railway engineers.

The consequences of the Australian railway gauge decisions are still being felt, and paid for, 130 years later. Interstate tracks are slowly being changed to standard gauge, often by duplicating tracks. Blame for the decisions of the late 1800s is often sheeted to "politics." Rivalries between companies and colonies and even individuals, power struggles, and deep-seated prejudices were the cause. We have to be non-standard because our requirements are special. These same arguments are used by some technical communicators to avoid adoption of standards and as an excuse to implement a custom solution. Perhaps we, as a profession, need to move beyond the politics of standards and work together in a standard way.

Have anything to add when it comes to standards in technical communication? Feel free to post your comments below.

Posted on

Adobe Captivate: Sometimes a Smooth Mouse Path Isn’t So Slick

by Kevin Siegel Follow us on Twitter View our profile on LinkedIn View our videos on YouTube

I've written a few articles about Captivate's video mode including how to trim videos, use the Pan and Zoom feature, how to edit the mouse points, and how to publish video demos.

I received an email from a fellow Captivate developer who really liked creating eLearning using Video Demo mode but was lamenting the slow speed of the mouse.

"I was previewing the project. You could hear my voiceover audio and could see the mouse moving from point A to B," she said, "But the mouse was moving really, really slowly. The speed was fine a few days earlier but now it's so slow it's distracting."

The developer was sure she'd done something to the video to mess up the mouse tracking speed but was stymied to explain the exact cause of the trouble.

I asked her if she had trimmed the video.

"Why yes," she replied. "I watched your video on YouTube to learn how."

And with that, I had the reason for her troubles and the solution.

For whatever reason, when you trim a Captivate video, the mouse speed shown in the video after the trim point often reduces to a crawl. While I don't know why this happens, I do have a solution.

Choose Edit > Edit Mouse Points. On the Timeline, select the first mouse point after the trimmed section of the video.

Adobe Captivate: Mouse point selected on the Timeline. 

On the Properties panel, deselect Smoothen Mouse Path (Smoothen? Anyone think the option should be named Smooth instead of Smoothen?).

Adobe Captivate: Smoothen Mouse Path  

If you preview the video, you'll see that the mouse speed returns to its pre-trimmed speed. While you may need to repeat this process every time you trim a Captivate video, at least it's fast and painless.

It you'd like to see a slow mouse in action and how deselecting Smoothen Mouse Path fixes things, check out the video I created on IconLogic's YouTube channel.

***

Looking for instructor-led training on the top eLearning tools? We offer live, online training on Adobe Captivate, Articulate Storyline, Adobe Presenter, and TechSmith Camtasia Studio.We can also bring the same great training onsite to your facility. Interested? Contact us for details.
Posted on

Developing User Assistance for a Mobile World

Smartphones have sparked a huge, new software segment – the mobile app. They have also changed how traditional desktop software is being designed and developed. This creates an important pair of questions for user assistance professionals: What is our role going forward in mobile and how can we prepare to take that on? User Assistance does have a role in supporting mobile apps. As the mobile market continues to expand, this is becoming the next frontier for user assistance professionals.

This half-day, online workshop is designed to provide an introduction to key topics and also to foster discussion on the best ways to design UA for this new paradigm.

Registration includes an ePub copy of the book Developing User Assistance for Mobile Apps, PDF copies of slides and handouts, and access to a recording of the workshop.

Posted on

User Assistance: HUDs in Technical Communication

by Tony Self Follow us on Twitter View our profile on LinkedIn
 
Did you ever see the 1986 movie "Top Gun?" If so, perhaps you recall seeing gun-sights, cross-hairs, warning messages, and air speeds displayed as green text on the cockpit windshield of the jets. What you saw in the movie was an early Head Up Display (HUD). If Top Gun is too old for you, how about Iron Man? HUD was featured prominently in that movie as well.

While HUDs may seem like something you'll find only in fighter jets or the movies, they are actually creeping into everyday life. For instance, HUDs are now installed as standard equipment in many cars displaying speed, distance, and messages onto the windshield. Drivers don't need to move their head up or down to read the text; they can keep looking straight ahead.

If your car isn't equipped with a HUD, you can use your smart phone, download a HUD app, place the phone on the dashboard, and reflect an inverted readout onto the windshield. And you can purchase HUD navigation systems (such as the unit shown below from Garmin).

Garmin HUD   

There's a new type of HUD that's attracting lots of attention: Google Glass. Glass isn't the only product of its type on the market (there are dozens), but it attracts the most publicity. These wearable technology products display text in a tiny HUD in a pair of lens-less spectacles. The text displayed depends on the application; it could be the current time, an appointment, alerts… but it could also be procedural information, checklists, or product descriptions.

What does HUD technology have to do with technical communication? HUDs will provide innovative new ways to deliver technical information. For instance, Virgin Atlantic is currently testing Google Glass at Heathrow Airport. According to CNN, "The airline is conducting a six-week experiment with the wearable technology for passengers in its Upper Class Lounge at London. With data flashing before their eyes, staff can update customers on their latest flight information, as well as weather and events at their destination."

Google Glass being tested at Virgin Atlantic

 Source: CNN

If the Virgin Atlantic tests prove successful, the opportunities for technical communicators are endless. Beyond simply documenting HUD devices and applications, technical documentation and eLearning content could actually be displayed on a HUD. There will be challenges of course. Writers looking to create content for HUDs will need to embrace writing techniques such as minimalism and separation of content and form. Nevertheless, it will be possible for technical communicators to one day deliver to this new media… a layer above reality. 

Posted on

Localization: Training & Development in the Czech Republic

by Jen Weaver Follow us on Twitter View our profile on LinkedIn

Frequently ruled by outsiders in its history, the Czech Republic now faces happier times. Let's take a jaunt over to Central Europe and explore some common cultural facts about the Czech people and their expectations when it comes to T&D.

Test Your Knowledge of Czech Culture:

  1. True or False. Bohemia is another name for a section of the Czech Republic.
  2. Is "Czech" the English or Czech spelling of the name of their language?
  3. True or False. Budweiser beer was named after a town in the Czech Republic.

Quick Tips for Training & Development in the Czech Republic1:

  • The Czech Republic is fairly young as a free state, a designation achieved in 1993, and it joined the European Union in 2004.
  • Remain alert on the roads; many drivers tend to be erratic. Pick-pocketing on the street is also quite common.
  • Czechs identify truth through both feelings and objective facts. The ideologies of humanitarianism and democracy also hold prominent roles in day-to-day decisions.
  • Czechs value personal achievement and are motivated by individual recognition. As such, formal degrees are respected, so be sure to mention your educational background and even include it on your business card.
  • While relationships are highly valued, it's often a slow process to build deep friendships. Allocate time for chit-chat so your students can get to know you. Part of building relationships is asking questions about each other's family.
  • Another fun family topic is dogs, as the Czech people are particularly fond of this furry friend. Dogs are even allowed in many restaurants.
  • The eldest or highest-ranked person will enter the room first. If there is a tie, the male counterpart will enter before the female.
  • Many Czechs feel that past Communist rule has robbed them of many years' worth of profits. This may cause high-even unrealistic-expectations on returns, so be mindful when making agreements or establishing future goals.
  • If training directly in Prague, you may be able to avoid hiring a Czech translator, but it's recommended even within the city.
  • A typical Czech holiday is four weeks annually, with peak travel times from mid-July to mid-August. When possible, avoid scheduling classes during those months.
  • Decision-making is a slow, methodical process.

Knowledge Test Answers:

  1. True. The easternmost part is Bohemia, and the westernmost part is known as Moravia.
  2. English. This spelling came via the Polish language. The Czechs call it "Česká."
  3. True. The town was Budweis, now called Ceské Budéjovice. The Czechs are known for making extraordinary beers, and any beer drinker would be happy to discuss the topic.

References:

 1Morrison, Terri, & Conaway, Wayne A. (2006). Kiss, bow, or shake hands (2nd ed.). Avon: Adams Media.

***

Developing international training and development materials? Contact Jen at Carmazzi Global Solutions.