Posted on

Difference Between Run and Execute in Technical Documents

Technical writing is about getting the small details right.

The difference between the almost right word and the right word is the “difference between the lightning-bug and the lightning.” Mark Twain

So, when writing a user guide, should you say, Run or Execute?

From one angle, it doesn’t seem to matter. Everyone knows what you mean, right?

Well, maybe.

What’s important are:

  • Readership – who is reading the document?
  • Context – where are you using the verb or phrase?
  • Consistency – are you using the phrase or verbs consistently in other documents?
  • Run and Execute are neither good nor bad.

It’s knowing when to use them that matters.

So, when do you use Execute instead of Run.

Run v Execute as Nouns and Verbs

First, nouns and verbs…

As a noun:

An executable is a file with an .exe extension. For home users (i.e. non-techies, your Mom, your Dad), use program file instead.

Try to use executable and .exe as adjectives, not nouns.

Use the article ‘an’ with .exe, for example “an .exe file.”

Good

an executable program

the program.exe file

Not so good

an executable

program.exe

Execute v Run for Target Readers

Again, for home users, avoid using execute except to follow the user interface. Use run instead.

Use run when describing macros and queries.

Good

To run the program, click Execute.

You can pause Disk Defragmenter so you can run other programs.

Not so

Stop Disk Defragmenter to execute other programs.

Exceptions

The exception is when writing technical documents for software developers who seem to prefer to use execute instead of run. Run seems to be used more for reports and batch files.

Run is preferable, however, where it does not cause any loss of meaning.

Examples of where Execute is preferred

Executing in SQL, for example.

Executes a command string or character string within a Transact-SQL batch, or one of the following modules: system stored procedure, user-defined stored procedure, CLR stored procedure, scalar-valued user-defined function, or extended stored procedure. The EXECUTE statement can be used to send pass-through commands to linked servs. Additionally, the context in which a string or command is executed can be explicitly set. Metadata for the result set can be defined by using the WITH RESULT SETS options.

See: http://msdn.microsoft.com/en-us/library/ms188332.aspx

Methods – IUICommandHandler::Execute method

Responds to execute events on Commands bound to the Command handler.

See http://msdn.microsoft.com/en-us/library/windows/desktop/dd371489(v=vs.85).aspx

As an example, you might want to assign all dynamically generated code a very limited set of permissions, such as Execute (which permits the assembly to execute, but severely restricts what that code can do).

When to use Run? During Runtime?

Rachel Appel writes, “Windows 8 is changing how and when applications run, and you’ll want to understand the nuances of the new application lifecycle

All Windows Store apps have four states: not running, running, suspended and terminated. When you launch an app, it runs. Background tasks are lightweight classes that run periodically, under certain restrictions, while the app is technically not running.”

See http://msdn.microsoft.com/en-us/magazine/jj660301.aspx

Run Your App

Run is most always used when describing an app, or something you do with an app. Look at this example:

When Xcode launches your app in debug mode, it immediately starts a debugging session. If you are running an iOS app, Xcode launches it either in iOS Simulator or on an iOS device connected to your Mac. If you are running a Mac app, Xcode launches it directly on your Mac.

https://developer.apple.com/library/ios/documentation/

Example – About deploying and running apps in the emulator

When you run an app for the first time in the emulator, the following events occur:

  • The emulator starts.
  • The emulator loads the operating system.
  • The emulator displays the Start screen. Your app is deployed to the emulator.
  • Your app runs on the emulator.

That help?

Let me know if you have any questions.

 

Posted on

Robohelp: Why Short Topic Names Improve Navigation

The length of the topic title, i.e. the number of characters, needs to be considered when creating topics for online help.

fuel-signLet’s say you’re creating different topics in RoboHelp. Procedures, reference, and conceptual materials. Each of these needs an intuitive and meaningful name. That makes sense.

However, you also need to consider the length of the topic title (i.e. the number of characters) when it appears in the side Navigation.

The side Navigation appears on the left of the Help system when viewed online.

Topic Title: Name Length

The problem with the length of the topic title is that, depending on the user’s settings, they may only see the first two or three words.

So, if I wrote:

the length of the topic title

they’d only see

the length of [and the rest would be hidden behind the frame]

which isn’t much use.

One way to fix this is to frontload – put the most important word or phrase first – and then add the rest. For example:

  • [6 words] Topic Title: Length of the Name or
  • [5 words] Topic Title: Length of Name or
  • [4 words] Topic Title: Name Length

Remember, users scan for information. If you frontload the critical word, term, phrase, or verb, the user is likely to find the relevant information faster. It also means they don’t have to drag the navigation pane to see the rest of the topic title.

This may not seem important – can’t they just drag it? – but with more of us reading content online, using different devices, different browsers, and on small screens, making the user have to work harder to find information is best avoided.

Remove clutter from headings

A second tactic is to delete filler text or phrases that add little value.

In the example above, we reduced the word count from six to five to four. Was anything lost in the process? Not much.

You can also delete filler phrases, such as Descriptions in Reference Descriptions of the XXX Window, as description is implied. In other words, the user knows they’ll be getting descriptions of the window, for example. Likewise, words such as Information can also be deleted.

A final suggestion is to remove definite articles.

This reduces:

Reference Descriptions of the XXX Window

To

Reference for XXX Window

These are different ways to reduce the length of the topic title and the number of characters when creating online help.

With that said, what’s more important is not to reduce or change the headings to make them shorter but understand why we need to do this. How can we improve the help system for the user?

Maybe there’s a smarter way to create topic headings.

Let me know.

Posted on 15 Comments

User Guide vs User Manual – which is right?

Let’s say you’re setting up a new Tech Docs Dept.

You need to create new guidelines, style guides and naming conventions.

Should you call the user ‘documents’ User Guides or User Manuals?

Which one is right?

I was asked this question by a colleague in India who is setting up a Technical Publishing Dept in Bangalore.  He wants to go with user guide—me too, actually.

  1. When I worked in the UK, it was (mostly) referred to as a User Manual.
  2. Whereas in the US, it was a User Guide. I think the Americans (and me!) like things to be short and to the point. Guide is just that little bit quicker to write, especially when you’re creating MS  Word templates.

Saying that, there is no right and wrong, but I did a little fact finding first.

What Google says about User Guides

I searched Google and came up with these results.

  • 15,600,000 for “user guide”
  • 10,700,000 for “user manual”
  • 5,210,000 for “user’s guide”

What surprised me here was that User’s Guide was so widely used. I’ve always found this a bit annoying. I just don’t like apostrophes, I guess.

Top 5 Most Popular User Guides

A quick check on the most popular user guides showed the following. Not what I expected.

IBM Technical Documents

Next, I checked IBM and Microsoft  to see what term they used.

  • 15,324 for user guide
  • 1,047 for user manual

So, they prefer user guide. Though, you’d think they’d make this mandatory. Of course, it’s not easy when you have offices in every corner of the world, so let’s cut them some slack.

Microsoft prefers User Guides too

The folks are Redmond were more consistent with

  • 1.8 million for User Guides and only
  • 73k for User Manuals

And, to be fair, many of the user manuals were actually guides when I checked. Someone check that search engine!

Is Apple different?

Yes, of course.

Apple prefers the term User’s Guide. Like I said, I never bought into this. I prefer short, snappy titles. We don’t call them System Administrator’s Guide, do we?

Well, of course, some do.

Things to consider when naming your documents

  • Avoid obscure or unique terms for your documents. Use industry standard terminology.
  • Ask your target audience what they expect.
  • Create a Style Guide or adopt one, e.g. the Microsoft or IBM style guide.
  • Develop a naming convention, e.g. a structure approach so that all documents are named, filed, and indexed correctly.
  • Develop a numbering convention. Show people how to number documents, for example, when to go from 1.1  to 1.2 and when to go from 1.2 to 2.0.
  • Be consistent.
  • Be patient when they get it wrong.

My career really began to take off when I saw myself as an ‘enabler’ rather than a writer. My identity of who I was changed from a guy who cranked out docs to someone who helps others get their projects done.

People want to learn, do your best to help them get there.

What do you think? What’s the most practical way to name documents and setup a new Technical Writing Dept?

Posted on 4 Comments

7 Ways to Improve Your Technical Writing

Here are seven quick tips to improve the quality of your technical documents. Continue reading 7 Ways to Improve Your Technical Writing

Posted on

What exactly do technical writers do?

Technical writers write technical documents that explain complex issues in simple, plain English.

Technical writers – also know as Technical Authors or Information Designers – write material that supports software and hardware systems.

They design, write and produce material that is delivered in print, soft-copy or as Online Help, such as that found in the Help section of programs like Word.

Posted on

How to Interview Tech Writers

Jane R. in Texas asks for some tips on interviewing tech writers, especially when using assessment tests. Her company is about to hire their first full-time writer and they have not done this before.

I’ve worked on both sides on the fence in the past, (i.e. interviewed and been interviewed) and picked up a few tings in the process. Hopefully, these will be of some help.

How much time should be allotted to complete the assessment test?

I’d suggest one hour. Some people will race through it, while others will deliberate over the grammar questions forever. Nonetheless, one hour should be sufficient time for them to complete the test. By allocating this amount of time to the test, you are also emphasizing its relative importance. If it were a simple 10-minute quiz, it wouldn’t carry the same weight.

Here’s a suggested approach for administering the test:

When advertising the vacancy, mention that an evaluation test is part of the assessment process. By saying this upfront, you will ‘weed out’ under-qualified writers who know that they would not pass the test.

When scheduling interviews, remind the applicants that there will be a 1 hour test. Explain to them what this entails, for example, that there is X number of questions on grammar, procurement, technology etc. Among other things, this illustrates your company’s professionalism as you are helping the applicants to prepare for the interview.

In turn, it would be unprofessional to spring the test on applicants when they turn up and catch them by surprise. Completing the test take about 90 minutes and some of your applicants may have other arrangements to consider, such as day-care, commuting etc.

When they arrive, I’d interview them first and then do the test. If they are unsuitable for the position, you can cancel the test and say that it’s not necessary at this point. For those who are suitable, I’d do the following:

  • Give them a pen and paper (always helps).
  • Glass of water/coffee.
  • Find a quiet room with a PC or laptop.
  • Give them a printout of the test (most writers like hardcopys).
  • Walk through the test so that they understand what’s required. They can ask any questions at this point.
  • Once they are ready, leave the room and let them do the test in Word.
  • After 20 minutes, drop in to see how they are doing. This is not to police them, but to see if they genuinely need any assistance.
  • After 60 minutes return and print out their test.
  • At this point, I’d suggest that they have a break so that you can score the test.

Once you’ve completed this, sit down and go over the scores. As everyone likes to know how they performed in a test, I’d walk through the results and discuss them with the applicant.
For example, if they scored poorly in one section, ask them how this area could be improved.

And finally, I’d thank them for taking the time to do the tests and hope that they’ve gained from it.

How many points for a passing score?

You could use 40 for a pass and disqualify anyone who comes in below this. Most experienced writers should get between 60-80 depending on their skills.

What I’d look for here is an imbalance in the scores. For example, if someone failed most of the grammar questions, but did very quite well in other sections, discuss this with the writer.

You may discover that many writers have no formal writing training and will suffer in the sticky grammar questions but compensate in other areas.

I’d use the scores/results to assist the overall interview process, i.e. you have material in front of you that you can discuss with the applicant and explore their abilities as a proposal writer.

You could also ask for their thoughts on this evaluation process and if they had suggestions to improve it. This might give you some insight into writers with potential management or creative thinking skills.

Posted on 1 Comment

Problems with Table of Contents in Word

James in North Carolina asks, “In Word, the Table of Contents is not displayed. Instead, I get an error message: { TOC\O “2-4″\H \Z \T “HEADING 1,1”}. How do I fix this? Is it a bug? “

I think the problem is to do with Field Codes.

Here are three suggestions:

1. In Word, go to Tools > Options > View tab and click off Field Codes (if this is selected)

2. Close Word.
Open Windows Explorer and search for Normal.dot.
Delete all copies of Normal.dot!
Re-open Word.
It will automatically re-create a new Normal.dot, which may be the correct default settings

3. In Word, on the Tools menu, click Options.
Click the Print tab, and then clear the Field codes check box.

Let me know if you know other ways to fix this problem in Word.

Ivan

Posted on

Controlling large docs in Microsoft Word

The main issues with creating long docs in Word tend to involve formatting, styles, graphics, tables, and bullets.

  • Formatting — cutting/pasting material directly from one file into another is best avoided as this will bring unwanted styles in the target Word file. Instead convert it to raw text and then import it.
  • Styles — create specific styles and avoid over-riding settings. Avoid using the default settings in the Normal.com template file.
  • Graphics – avoid using cut/paste graphics into Word. Instead, reference them with Insert Picture etc.
  • Tip: insert graphics only after all other content has been built! Tables — avoid the default Word auto-format settings. Bullets — use styles to create bullets. Avoid using the toolbar and menu options to create bullets. Avoid over-rides.

WARNING: Bullet lists cause more damage than any other feature in Word!

  • Always turn off Allow Fast Save and Save Auto Recover. See Tools > Options > Save > Allow Fast Save.

Developing Microsoft Word files with these pointers in mind will help reduce the file size and avoid corrupting the document template.

Posted on

Why do backward Ps appear in Word?

If you open a Word document and see what looks like large Ps at the end of every sentence, then the Show/Hide marker has been turned on.

Sometimes this gets turned on by accident or when you open a doc which as these turned on by default.

The the Show/Hide marker is used for examining the document’s formatting as it shows details of the underlying paragraphs, section breaks and page breaks.

You can turn off this by clicking the paragraph marker. This is usually located on the toolbar.