Winding Down

In April 2018, I decided to embark on a journey with SAP Canada as a full-time User Assistance Developer, which is a fancy title for a Technical Writer. I had always heard good things about working at SAP, so I wanted to give them a chance to impress me.

And they have. The people here are kind, ambitious, smart, and committed to producing high quality work. Although I will admit I was leery of working for a giant, international corporation, the company itself has proven to be ethical, smart, and treats its employees respectfully and even with great admiration.

So where does that leave Documentia Inc.? Honestly, I’m not sure at this point. I do still take on the odd small contract, usually editing or public speaking, but for the most part, the incorporation lays dormant.

I’m still answering my phone (514-791-3627), so if you need to reach out with ideas, opportunities, or if you have questions, please feel free to reach out to me.

Posted in Uncategorized | Tagged | Comments Off

Canaries

The truth of the matter is that the documentation of a product should be excellent. The grammar and style should be flawless and the information should be easy to read and retain.

Producing excellent documentation is not easy because it requires focus and a commitment to excellence, not only from the writer, but from the entire development team. It is quite literally a team effort: from the product designers, the coders, the testers, the trainers, and the writer. The documentation is the most human of all the aspects of a product because you cannot run it through a machine to find the flaws: it must be written, tested, and improved by human beings.

Bad documentation is the canary in the coal mine. Bad documentation is the absent red M&Ms. Bad documentation is the harbinger of bad omens.

If the documentation is bad, then that is a strong indicator that the company doesn’t care enough about the quality of its product from end-to-end. And you, the customer, are their latest victim.

Posted in Advice | Leave a comment

Crystal Anniversary 2018

Wow. LinkedIn just reminded me that I created my incorporated company Documentia Inc. 15 years ago this week. Back in 2003, I had already been writing professionally for 10 years, but a contract with CGI required that I get incorporated. Thus, Documentia was born.

Over these past 15 years, I have had the opportunity to write technical manuals, training guides, marketing copy, and narration scripts for databases, military simulators, 3D and 2D animation tools, telecom management systems, tech support systems, media management systems, digital media projectors, and much, much more. I have seen lots of interesting tech, all of it cutting-edge.

I have also had the honor of working with some of the most talented professional writers in this city and it has been a wild ride, so thank you to all those people who supported and collaborated with me on these projects.

Posted in Uncategorized | Tagged | Leave a comment

Launch DXtory

I’m having to record some application demos for a video tutorial at work and the application they use here is DXtory. I’d never heard of it before, but it seems pretty popular in the gaming industry.

Unfortunately, there doesn’t seem to be any documentation with DXtory, so I’m guessing they are relying on their loyal fans to explain it to the noobs. I tried searching for some documentation on it and went through some pretty pathetic video tutorials (that I usually gave up on 1/3 of the way through it) until I found this one:

In this video, the vlogger speaks a little quickly, but he gets to the point and has a clear idea of what he wants to teach. I took some notes for what applies to me and I’m off to the races!

I’m leaving this here just for my own notes, but I’m hoping you’ll find it useful. If you’re new to DXtory and you just want to start recording, here is the boiled-down procedure:

1. Lauch DXtory and launch the app to record.
2. Click Target tab, click on the app you wish to record, then click back in Target Information. The path for the target will appears in the Target Information panel, and the EXE file will appear in the Process List.
3. Click the Folder tab, click the Add icon and select the folder to which to save the movie file.
4. Click Benchmark to read the speed of your harddrive.
5. Click the Keyboard tab to assign the hotkey (default: F12)
6. Minimize DXtory, start your app, and press F12 to start recording.
7. Press F12 to stop the recording.

Posted in My Gadgets, Technology | Leave a comment

Romancing the RoboHelp

In my latest project, I’ve been reacquainting myself with the joys of Adobe RoboHelp and Framemaker to produce some online help. Please see my previous post about RoboHelp that I’ve updated to include RoboHelp 11.

I’ve been using RoboHelp for years, all the way back to the days when it was owned by BlueSky and it worked with Microsoft Word. Nowadays, the thought of using Word to write technical documentation makes me want to re-evaluate my life choices.

We’ve decided to go with the subscription model with Adobe, which means we get the latest and greatest versions as they are released. Sounds good on paper, but it’s lead to more than a few headaches. The Adobe community has been pretty good to suggest workarounds and we’re making progress.

For this post, I’m keeping track of a couple of tips and tricks that I’ve encountered in this journey. It’s mostly to act as a reminder, but I’m hoping it’ll help others.

Bug #1 — File Associations

April 2nd, 2017

At first, I had FM2015 installed, but I then upgraded to FM2017. To my surprise, Windows (7) did not update the file association to FM2017. I had to go into \Control Panel\All Control Panel Items\Default Programs\Set Associations\ to ensure that the associations had been made correctly.

Bug #2 — RoboHelp 2017 gets Nostalgic

April 2nd, 2017

If you are linking Frame files as your source files, RH2017 will attempt to access Framemaker when importing or updating these files. However, if you do not have FM2017 currently running, RH2017 will attempt to launch FM2015 automatically, which can lead to an error if 1) you do not have FM2015 on your system, or 2) your Frame file are in 2017 format.

The solution is that you need to ensure that the File Associations are correct (see Bug #1) and that you must launch FM2017 BEFORE launching RH2017 and they must be running at the same time.

Respecting the Conditional Text Rules

If your source files use a bunch of Conditional Text tags, you will need to be able to hide the Conditional Text that does not apply to the output your are trying to generate.

For example, if your source documents have content for ABC, DEF, and GHI products, to generate the content for DEF, you need to hide the ABC and GHI content.

Once you import your Frame files to your project, you need to indicate which Conditional Text needs to be hidden and which needs to be displayed.

To prepare the Output to respect the Conditional Text rules, follow these steps:

  1. In your RoboHelp project, select Output > Outputs(SSL). The Outputs(SSL) pod appears.
  2. Select the output type you want to use, right-click it, and select Properties. The Settings dialog box appears.
  3. Open Content Categories > Content<Default>, look for the Conditional Build Expression panel, and click Define. The Define Conditional Build Tag Expression dialog box appears.
  4. Select the Conditional Text tags you want to display (in the Available tags list) and move the ones you don’t want to the Exclude from output list.
  5. When prompted, provide a name for this type of Conditional Text output.
  6. Either click Save to save these changes, or click Save and Generate to save your choice and generate the output immediately.

Defining the Default Topic

The first topic that appears in the online help when you launch it is defined in the Output model (ex: Webhelp Pro).

Note: If you want to pick a topic other than the one you created when you started the project, make sure you generate all the pages for your project first.

To select the default topic, follow these steps:

  1. Select Output > Open > Outputs(SSL).
  2. Right-click the output model you wish to use and select Properties.
  3. Open Content Categories and select Content<Default>.
  4. For the Default Topic field, click Select and pick the topic you want to use.
  5. Save or Save and Generate.

Hypertext Links Don’t Convert

I had a Book file with chapters in Frame that I would convert to HTML5. Everything was converting over nicely, except the hypertext links to external website (like the company website or an FTP site). The text appears in the traditional blue link color, but there’s no link there to click.

In Framemaker, I highlighted the text and insert a Hypertext marker (message URL http://www.documentia.ca). When I save this as PDF, the hypertext is live and works great. When I convert it to WebHelp, the text appears in blue, but there is no link.

When I looked at the page source of the converted HTML5 (where the hyperlink was dead), I noticed there was a span marker called FM_urllink, but no hyperlink. So on a hunch, I removed the character style in Framemaker and kept the marker (Hypertext: message URL http://www.documentia.ca). I updated the Frame file, regenerated the page, and voila! The link works!

There’s something about applying a character style on the text that has the Marker that hides the hyperlink in the converted HTML5 page.

Now while the link still works in PDF, this means that links in PDF cannot be highlighted with a Character style. For now, the work-around I can see is to use Conditional Text to mark one link as Print only and another as HTML only.

Mapping Styles from Framemaker Source Files

In this project, I wanted to have an increased left/right margin for the Body text (including Bullets, Steps, Step Ghost, Bullet Ghost, etc). I really didn’t want the text to go rampaging from one edge to the other, especially if the browser went full-screen.

To make this process easier, you need to open the Project Settings > Import tab, enable the Apply Framemaker Template option, and select a chapter from your Framemaker document that has all the styles you use in the book. This will allow you to make changes to the output styles across the whole project.

Then use the Edit Conversion button to make your changes.

To prevent having to regenerate the project every time to check the layout changes, select a topic from the Project Manager that has the styles you are changing, right-click it, and select View.

Once you are satisfied with your changes, regenerate the output and verify that everything has worked out.

Posted in Advice, Projects, Technology | Tagged , | Leave a comment

Writing and Editing

Writing is like building a house in the woods where no house previously existed. Re-writing is like demolishing a house in the woods and rebuilding it to suit your needs and stylish flair.

Editing is like:

  • inspecting every door and window frame to make sure they are level
  • checking every nail holding the house together and hammering them back in
  • checking every screw holding the house together and tightening them
  • arguing with the architects when they insist “The doors/windows are more efficient when crooked!”, “The nails are supposed to stick out!”, “The screws are supposed to be loose by design!”
Posted in Advice, Fun, Writing | Tagged , , | Leave a comment

Strengthen Your Writing

Reading technical documentation is nobody’s idea of an enjoyable night in. You could try to make it special with some wine and candlelight, but it’s still going to be a stretch. Therefore, the documentation needs to strike that balance between being complete while using as few words as possible. If you use too many words, no one will want to wade through it to find the information; if you use too few words, the information won’t be complete or useful.

Flexing your Vocabulary

One of the ways to strike that balance is shorten sentences by using strong verbs, descriptive nouns, and common language. While the written word and spoken language are two different beasts, you can often simplify words and sentences by asking yourself “If I were explaining this to someone, is this the word I would use? Who speaks this way nowadays?”

For example,

BAD: “In order to reduce obscurification, one must employ the appropriate level of verbiage that targets the desired balance of plenitude while being spartan in the use of colloquialisms.” (I almost fell asleep in the middle of writing that sentence.)

BETTER: “To ensure written clarity, you need to strike a balance between being complete and using a minimum of words.”

BETTER: “Make sure that your writing is clear and complete by picking your words carefully, crafting your sentences to be short and strong, and remove any language that drags.”

TOO MUCH: “To be clear, don’t use too many words.” — This tells the reader what to do, but not how to do it.

Reduce your Phrasing

While trying to sound literary the way Ms. Crabapple always insisted, writers sometimes pad their sentences with too many introductory words. More words do not make you look smarter: being smart and mindful when using strong, snappy words make your sentences come alive.

The following are some common phrases that I’ve seen that can be reduced easily, making for stronger, punchier writing:

  • In order to run: To run
  • Whenever you want to run: To run
  • It may be desirable to run: You may need to run
  • In order to utilize your running shoes: To use your running shoes
  • Please select the following running shoes: Select the following running shoes
    (I know it seems rude, but never politely beg the user to following the instructions)
  • A large number of people run: Many people run

Passive Voice

When possible, try to avoid using the Passive Voice. In the Passive Voice, the subject that is performing the action is unclear, so you end up with long sentences that jump around to avoid naming anyone specific. You can get around this by speaking to the reader directly using the 2nd person voice (You).

BAD: “The required information is acquired upon successful application of sufficient force to the button.”

BETTER: “To get the information you need, press the button.”
BETTER: “To get the information, you should press the button.”
BETTER: “To get the information, press the button.”

There are times when using the Passive Voice is unavoidable. Therefore, it should be used sparingly. Er, I mean… *you* should use the Passive Voice sparingly.

Posted in Advice, Writing | Tagged , | Leave a comment

Promo Script Writing Project

So I have been having to sit on this for about a week, but now I’m allowed to show it off. Here’s the story.

In mid-December, I was contacted by an office furniture-design company in the Montreal area called Group Focus (groupefocus.com) who asked me to write a script for them for a promotional video. They were going to a conference and were asked to put together a promo video for their company.

For this video, they decided they wanted to focus on their people rather than their products/services, and they wanted to go with a wolf/nature theme. I wrote them a script, they loved it, I did the narration, they still loved it, and here’s the final product.

Posted in Projects, Writing | Tagged , , , | 2 Comments

Fixing the Giant Ship

I was looking up some stories and I came across this Islamic folktale:

The following is an incident about an engine failure in a giant ship. The ship’s owners tried one expert after another, but none of them could figure but how to fix the engine. Then they brought in an old man who had been fixing ships since he was a youngster. He carried a large bag of tools with him, and when he arrived, he immediately went to work. He inspected the engine very carefully, top to bottom.

Two of the ship’s owners were there, watching this man, hoping he would know what to do. After looking things over, the old man reached into his bag and pulled out a small hammer. He gently tapped something. Instantly, the engine lurched into life He carefully put his hammer away. The engine was fixed! A week later, the owners received a bill from the old man for ten thousand dollars.

“What?!” the owners exclaimed. “He hardly did anything!”

So they wrote the old man a note saying, “Please send us an itemized bill.”

The man sent a bill that read:

Tapping with a hammer $ 2.00
Knowing where to tap $ 9998.00

Effort is important, but knowing where to make an effort in your life makes all the difference.

Posted in Advice, Writing | Leave a comment

Professional Body Language

When you are working with people, either as a co-worker or as a manager, and you have someone explaining something to you that either you don’t understand or you think is outlandish, you need to hide these emotions from your body language.

Not that you need to just accept whatever people are telling you. Sometimes people are confused, inexperienced, or just plain wrong. You can still work with these people and either get them on your page, on your side, or they might have insight you have not yet considered.

But when they are explaining it to you, be careful what you are broadcasting. If they see something in your body language that tells them that you think they are stupid or a waste of your time, they may not want to work with you anymore, or they may actively work against you.

Posted in Advice | Tagged | Leave a comment