Posted on

[Checklist] How to Review Troubleshooting Guides

troubleshooting-guide-review-checklist

Making a list, checking it twice… or three times…

How do you test your Troubleshooting Guide after you write it? One way is to create a checklist and test each part individually.

This also helps System Administrators and Software Testers to double-check that all procedures have been completed correctly.

Ok, less talk from me. Let’s take a look.

Use the If/Then Format

Phrase the checklist items using questions, if/then statements, and notes.

For example:

Ask the question:

  • Is the core running?
  • On Windows, check for the appropriate service name.
  • On Linux, check for the appropriate daemon name.

Describe how to verify this is correct, for example,

‘Use the sysmgr command to verify that the System Manager is active.’

Other examples of questions and verification steps:

  • Was synchronization started from the console or the command line?
  • Are the directory sources currently running? Use the console to verify that modifications synchronized in the expected direction.
  • If synchronizing users in one directory source, were these users created in the other directory source using the sync command?

Add Explanatory Notes

In some cases, you need to provide additional information to help the reader understand the underlying problem. For example:

If this was not true, describe what the Sys Admin should do, for example:

Run the sync command whenever there are existing users.

Then add an explanatory note:

Note: If you do not update existing users, accounts information will conflict.

Checklist using If-Then-Verify Procedure

Use if-then-verify checklists to test technical documents.

This works as follows:

  1. If an error occurs
  2. Then do this to check it.
  3. Verify that is works by doing the following

For example:

  1. If the user account is not replicated from the Active Directory to the Directory Server,
  2. verify that all mandatory attributes in the Directory Server are specified.

Checklist using If But Verify

In this example, one process succeeded, but a second failed.

  1. If synchronizing is replicated to the Directory Server and the user creation succeeded,
  2. but the account is unusable,
  3. verify that the user name is valid.

Provide additional information for the user to resolve the issue:

For example, if you specify an account that exceeds the maximum allowable length, the account will be created but cannot be used until you rename it.

PS – Download your Troubleshooting Guide here.

Posted on

Proof-reading Checklist for Technical Documents

Is there anything worse than sending out an important document and then, just when it’s gone, finding a typo?

Always leave some time to check your documents before you send them out. Here’s a checklist to get you started.

crone-park (65)

Proof-reading Checklist

  1. Select the entire document – CTRL+A – then click the Language option at the bottomrof the screen. It might say English (United States).
  2. Mark the selected text as the language it should be set to. Click Set as Default.
  3. Press F7 to start the spellchecker.
  4. In the spelling results, click ignore all to ignore the same issue throughout the document. Click Add if you want to intentionally add this word to the dictionary. Be careful if your dictionary is networked as this will be added to their shared dictionary.
  5. Watch for phrasing consistency, e.g. Note and NOTE, iOS and IOS.
  6. Careful making global changes, for example, don’t change IOS to iOS across the document as, fro example, in the code samples, we use IOS all uppercase, not mixed case.
  7. You select and clear check boxes, not untick or deselect. Note it’s check box, not checkbox.
  8. Rephrase text such as you are checking to check, or when you are installing the printer, write install the printer.
  9. When writing file formats, use lowercase. So, it’s an .ipa file not IPA file. An .ipa file is an App Store Package.
  10. Remove abbreviations. Change P4 to Perforce.
  11. Remove rogue double spaces.
  12. Number tasks if they must be performed in a specific order. So, instead of writing, Build the solution in the following order and use bullet points, number each step in relation to the sequence it should be performed. Likewise, avoid using a, b, and c. One tip: select the letter so it turns grey. Then type the number. This instantly changes the letter to a number.
  13. Remove & characters that have crept into the document, for example, find&replace. Instead write Find and Replace. The exception are terms where is should be used, such as R&D, or where it is at least acceptable.
  14. File, Info tab, then update the Properties. Click Show All Properties to see all fields which need to be updated. Remove any legacy text if you’ve copied your working document on another document.
  15. Full stops. If you finish bullet points with a full stop aka period, then check that are all applied.
  16. Ignore text during spell checks.
  17. When everything is finished, Right-click on the Table of Contents, then select Update Entire table. This updates the entries in the TOC and also the page numbers.

If you want to intentionally exclude a block of text, or a specific style, from the spell check:

  1. Select the text that you want the spelling and grammar checker to ignore.
  2. On the Review tab, in the Language group, click Language, and then click Set Proofing Language.
  3. Select the Do not check spelling or grammar check box.

What else would you add?

Posted on

How to Test Technical Documents

This checklist helps you test User Guides and other technical documents.

eye-test

The first step is to ensure the following is in place.

  1. Setup the necessary technical environment. Make sure this reflects the user’s settings or as close to as possible.
  2. Print out the procedures. Follow the instructions as per the document. Aim to identify any gaps in the steps. Likewise, see if additional notes or warnings should be added.
  3. Examine the screenshots. Does these provide real value? Do the screenshots reflect how the window or dialog box are populated? Is there data in the screenshots? If not, replace with something more meaningful.
  4. Does the introduction orient the reader?
  5. Does it highlight the necessary and mandatory prerequisites that must be performed?
  6. Are the sections in a logical order? For example, is it arranged based on the user interface layout or on commonly performed tasks?
  7. Is there an index? Are the entries used in a meaningful way?
  8. If online, have meaningful keywords been added to the search engine?
  9. Comprehensive – are all scenarios covered in the document? In other words, in addition to checking that the materials in the document are correct, you have to consider if other procedures are missing? To do this, you need to examine the application and see if, from a user’s point of view, if all tasks have been documented.

User Guide Checklist

After this, examine the document using the following checklist.

Visual Cues

Have you provided visual cues to help the reader use the manual, understand concepts, and help them digest information faster?

You can achieve this by using some of the following:

1. Headings

2. Bullets

3. Bold

4. Arrows

5. Illustrations

Support Different Learners

Have you developed content that supports the following learning methods:

1. Visual

2. Audio

3. Touch

Examples

Provide the following types of examples to help the reader understand the materials:

1. Concrete examples, for example, how to perform a specific task.

2. Abstract concepts

Document Format

Have you delivered the user guide in a file format the suits the reader? For example, do they want the document in PDF or as Online Help or both?

Other factors to consider include:

1. Size – remember to optimize the PDF before publishing and to ensure it downloads fast.

2. Online/print – prepare the document in both online and PDF, if necessary.

3. Software/hardware environment – will the reader need any special software to view the documents?

4. Binding – if delivering a hardcopy, make sure the binding is reliable, so pages don’t fall out after a little use.

5. Protection – if the document will be used outdoors, make sure it is weather-proof.

Document Structure

Have you checked that the guide includes the following?

1. Headers, footers, navigation bars

2. Table of contents

3. Cross-references/links to related procedures/documents

4. Is each topic self-contained? In other words, can you perform the task from start to finish without having to go to another page?

5. Is there adequate white space?

6. Have you avoided large blocks of text?

7. Does the document separate conceptual, procedures, and reference materials?

8. Index

9. Glossary with product terminology and industry terms

Introduction

In this section, you should introduce the User Guide and cover the following areas:

1. Intended readers – have you identified the different user types, for example, system operators, home users, and experts?

2. Have you identified the assumed level of experience and highlighted the sections of user guide which apply to them.

3. Software version – is the software release the User Guide refers to identified?

4. Purpose – have you described the purpose of the system and User Guide?

5. How to use User Guide document – have you described the intended use, section contents and relationship between sections?

6. Related documents – have you identified related documents?

7. Conventions – have you described symbols, conventions and syntax conventions used in the guide?

8. Problem reporting instructions – provided an email address so readers can contact you if they find an error or omission?

Overview

Have you outlined how the system works at a high level?

1. Identified key functions?

2. Inputs and Outputs – identified inputs what you, the reader, need to enter, and outputs, what you expect in response, for example, reports?

3. Provided further detailed explanation, if necessary.

4. Assumptions on user expertise, for example, experience or proficiency in related areas or previous training.

Procedures

This is usually the heart of the user guide. For each task, document the following:

1. Explain how to get started, for example, specific settings they need to make to use the application, such as installing a plugin or checking that a specific version of Java has been installed.

2. Describe the different functions of the system.

3. Provide cautions, warnings, and recommendations.

4. For each procedures, identify where in the application you perform this task, input operations and expected results. If necessary, include a screenshot that helps the reader understand the task. Avoid pointless eye candy screenshots.

5. Required parameters, optional parameters, default options and order/syntax

6. Provide examples

7. Identify known issue, likely errors, possible causes, and resolutions.

Reference

Have you identified and described all system capabilities, for example,

1. Describe the purpose of different buttons on the menu bars, what happens if they get greyed-out, how to change this, why this occurred, and how to reset window layout.

2. Describe the purpose of each field, identify mandatory settings, minimum or maximum settings, recommendations, and data input types.

Error Messages and Recovery Procedures

Have you identified and described all error messages and recovery procedures, for example,

1. Document all error messages.

2. Identify root cause.

3. Suggest recovery procedures

Glossary

Have you provided a list of ambiguous terms or terms users may not know to the reader.

Index

Have you provided an index? This is recommended for User Guides of 40 pages or more.

Document Control

Have you provided Document Control, Signoff and Change Record information?

PS – if you want the PDF to this, head over to my channel on SlideShare.

Posted on 5 Comments

Review Camtasia 6: The Good, Bad and The Ugly

I upgraded to Camtasia 6 at the weekend (from v4) mostly to import and edit .MOV files. These are created by my faithful Canon Powershot when I shot videos. Sony makes AVIs. The other reason was to do more heavy lifting with Camtasia. I have tons on material on the hard-disk and want to get these into screencasts. So, what the verdict?

Review Camtasia 6

Price – $149 not cheap but not as expensive as Adobe Premiere.

Key features

  • Import and edit MOV files
  • Independent audio edits (saves me doing audio in Audacity)
  • 3D tilt (can’t find where to do this, yet) and oodles of
  • Special effects

The good – What I liked

The user interface is nice, no nutty changes a Ia Microsoft Office and ribbon bars

Presets for blog, YouTube etc means it will help you produce files that best suit these formats. For simple videos, this is fine. You can do your own monkeying around as well, e.g. change frame rates.

the bad – What I don’t like

Audio enhancements are hit and miss. Sometimes makes the voice lovely and rich (hey, why not!) other times I sound like I’m under-water.

Number of un-dos seems limited. I love to un-do.

the ugly – real Problems

Freezes with files over 4 MB. These are (for me) small files, so I need to reboot all the time. Big problem. (What memory do I have? 80 GB of hard disk and 2 GB of RAM – thought that would be ok.) This is a killer. Files more than 3MB cause Camtasia to freeze. What this means is that when I try to make an AVI, MP4 or MOV for YouTube, the thing locks, usually at 19-25%. Close all apps, re-boot and try again. No joy.

Smartfocus won’t start – Camtasia thinks I’m using an older version, e.g. v5, and so won’t start it. I’m on 6. Can’t get it to work. See the error message.

MOVs won’t import – this is a horror! According to the site ‘Large MOV files not importing into Camtasia. Camtasia will crash or give a no codec message upon importing. This is a known issue that will be fixed in a future release. As a workaround, try creating smaller MOV files from other programs when bringing them into Camtasia.’ I’ve done this and still no luck. Off to contact Tech Support.

MP4s won’t import – No Codec available error message. Contact Tech Support.

FWIW I download all the codes I can find on the site, re-boot and… no joy.

What to do next?

Not sure. Have downloaded all the codecs I can find, re-booted the pc, cleared the cache, closed all apps and sent some emails to Techsmith. Now, I’m waiting…

Can you help?

If you’ve had these type of issues, can you let me know what you did to fix this?

Posted on 18 Comments

Robohelp vs Doc-to-Help? Which is best for Online Help?

Robohelp or Doc-to-Help?

My client has given me permission to use whatever tool I want to do the next batch of tech docs — and they’ll buy the software. No cost to me.

Which one should I choose?

Robohelp or Doc-to-Help

Doc-to-Help was the first help authoring tool (HAT) I used in my technical writing career. We’re talking quite a while back now. Since then Robohelp has overtaken it as the tool of choice for technical writers, especially as it’s now owned by Adobe and bundled with its Technical Communications software pack.

For Doc-to-Help

  • I feel this product is under-estimated. Other technical writers (more knowledgeable than me about HATs) recommend it.
  • Opportunity to broaden my skillsets (self-interest here and not to the client’s advantage!)
  • Rapid response from Component 1 (product owners) when I contacted them. Very helpful. Only Techsmith (esp Betsy Weber) were more helpful.

Against Doc-to-Help

  • Price is not cheap
  • Will there be enough qualified Doc-to-Help experts to take over this project when I move on?
  • Does it integrate with other technical writing apps and/or Microsoft Word?
  • Worried about lack of community support, i.e. from other technical writers, if I need help.

For Robohelp

  • Oceans of Doc-to-Help experts to take over this project
  • Part of the Adobe Tech Communication suite. Maybe get discount.
  • Arguably the industry standard
  • Plenty of tutorials online if I get stuck

Against Robohelp

  • Price
  • Concern that there is no real advantage in getting the Tech Communication suite anyway as we (i.e. the client) won’t use it once I’ve left
  • Found the user interface horrible to work with last time. Admittedly, this was four years ago but you know how these things stick.

Another alternative is Madcap Flare.

What do you think?

If you were in my shoes, what would you do?

Posted on 6 Comments

Review EPIC Editor – XML and DITA Authoring Software

Of all the technical writing tools I’ve used over the years, Epic Editor was probably the most impressive, especially when it came to doing tech documents that involved DocBook and Dita. It was difficult to learn – no point pretending otherwise – but once I got the hang of it, I used it non-stop for over 2 years. Then I switched companies are haven’t had the opportunity to use it again. With that in mind, here is a brief intro to EPIC Editor, Ivan’s favorite XML Authoring Software!

Update:  Epic Editor is now called Arbortext Editor. You can learn more over here: http://www.ptc.com/products/arbortext-editor

Continue reading Review EPIC Editor – XML and DITA Authoring Software