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.
Proof-reading Checklist
Select the entire document – CTRL+A – then click the Language option at the bottomrof the screen. It might say English (United States).
Mark the selected text as the language it should be set to. Click Set as Default.
Press F7 to start the spellchecker.
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.
Watch for phrasing consistency, e.g. Note and NOTE, iOS and IOS.
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.
You select and clear check boxes, not untick or deselect. Note it’s check box, not checkbox.
Rephrase text such as you are checking to check, or when you are installing the printer, write install the printer.
When writing file formats, use lowercase. So, it’s an .ipa file not IPA file. An .ipa file is an App Store Package.
Remove abbreviations. Change P4 to Perforce.
Remove rogue double spaces.
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.
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.
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.
Full stops. If you finish bullet points with a full stop aka period, then check that are all applied.
Ignore text during spell checks.
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:
Select the text that you want the spelling and grammar checker to ignore.
On the Review tab, in the Language group, click Language, and then click Set ProofingLanguage.
Select the Do not check spelling or grammar check box.
This checklist helps you test User Guides and other technical documents.
The first step is to ensure the following is in place.
Setup the necessary technical environment. Make sure this reflects the user’s settings or as close to as possible.
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.
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.
Does the introduction orient the reader?
Does it highlight the necessary and mandatory prerequisites that must be performed?
Are the sections in a logical order? For example, is it arranged based on the user interface layout or on commonly performed tasks?
Is there an index? Are the entries used in a meaningful way?
If online, have meaningful keywords been added to the search engine?
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.
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?
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.
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!
