Posted on

NEW: 39-page Quality Assurance Plan Template in MS Word/Excel

Looking for a Quality Assurance Plan template? We’ve spent most of the week polishing this fella and now he’s ready for prime time. See what you think.

Quality Assurance Plan Template

This template pack includes a 39-page Quality Assurance Plan Template in MS Word, an Audit checklist and Schedule Forms, and 7 Excel spreadsheets. You can use this template to write your first QA plan. It includes helpful explanatory text that walks you through the process of setting up your first QA project. You can change everything in the document – text, images, and tables. There are no special plug-ins, macros, or installation files. Just download the templates and get started.


Business Case Template - Download Here

Quality Assurance Plan Definition

The Quality Assurance Plan describes the approach to ensuring that software is delivered according to a set of agreed quality guidelines. It ensures that the:

  1. Project is managed, developed, and deployed correctly.
  2. Deliverables are of acceptable quality before delivered to clients.


In the Quality Milestones chapter, we’ve added a nice Note to the text to display some instructional text.


Here in the Documentation section, you can see how the chapter numbering, fonts, text, and tables are presented.

Why do you need a Quality Assurance Plan?

The Quality Assurance Plan ensures the project provides quality within the allocated resources, schedule, and budget.

How to use the Quality Assurance Plan

  • Address specific project processes and deliverables.
  • Establish criteria that defines the quality at each checkpoint or deliverable.
  • Identify roles and responsibilities for the quality assurance reviewers.
  • Define who, where and when quality reviews are performed.
  • Apply the Styles, such as those shown in the following screenshots, to ensure a consistent look and feel through-out the document.


Examples of Styles for the Body, Bullet lists, Notes, Table text and headers

Quality Assurance Plan Purpose

Use this Software Quality Assurance Plan to document the process, methods, standards, and procedures for your next software testing project. Use this document as a foundation for managing software quality assurance activities and project activities as documented in the Project Plan.

This Quality Assurance Plan will help you:

  • Identify the SQA responsibilities of the project team and the SQA consultants
  • Define reviews and audits and how they will be conducted
  • List the activities, processes, and work products to be reviewed
  • Identify SQA work products


Examples of different notes, message, and warning styles you might want to add to your Quality Plan

Who is this template for?

This template was written for QA Managers, especially those who may be new to this area and are looking for a little direction on how to get started. The forms, checklists, and spreadsheets will also help you get up to speed fast.


Learn more about the template pack here.

Posted on

MadCap Flare: How to Update Stylesheets


In the Madcap world of Flare (yes, I promise never to say that again), you can use stylesheets to give your tech docs a real edge.

For me, styles are one of the hidden secrets in Flare.

So, if you plan to publish your tech docs to PDF, Web, or HTML5, a crash course in CSS styles is maybe what you need.



How to Update Style Sheets

The nice thing about Madcap Flare is that you can control the design and layout with style sheets.

The ‘not so nice’ thing is that the UI takes a bit of getting used to. Once you understand how it works, it’ll be fine.

So, how do you start playing around with style sheets and jazzing up your online help?

You can change the colour, fonts, and layout of your online help (and printed documents), use the Stylesheet Editor.

To find this puppy:

  1. Go to Content Explorer, Resources, Stylesheets.
  2. Right-click or double-click on the style sheet to open the Stylesheet Editor.
  3. The Stylesheet Editor has two views:



  1. NB: If the list of styles is overwhelming, click Hide. This tidies things up and makes it easier to use.


Filtering the list of Styles

  1. By default, Show all Styles is displayed.
  2. If you click on the drop-down menu, you can select the Table, Images, or Headings This helps if you just want to work on a specific style family.


Filtering the Medium

  1. Medium means the output type, such as HTML5, PDF or Print.
  2. Click on the Medium drop-down menu, and select the output type you want to modify.
  3. Pay attention to this as you don’t want to change the wrong CSS settings.


Filtering Properties

  1. Click this drop-down menu to view the properties alphabetically, by property groups, or other settings.
  2. Advanced v Simplified View
  3. Click View Advanced to switch back to the View Simplified.


That’s it for this week.

Let me know if you run into any problems with your stylesheets. Sometimes one small setting can throw everything out of kilter.

Are we friends on Facebook? If not, jump over here.

Posted on

MadCap Flare: Conditional Text 101


Conditional text is one of those writing tactics technical writers love to talk about… but never seem to use.

It’s a shame as conditional tagging can save you a lot of time, especially if you have technical documents which share 90% of the content but the other 10% needs to be tweaked for each release.

This is where conditional tagging comes in.

Applying Condition Tags to Online Content

Before we get into it, we should explain a little bit about conditional tags.

Here’s an example. Let’s say you have a core product set, but you modify the product name for different clients. Instead of find/replace by hand, you can apply conditional tags that tell Flare:

  • If content contains product name 1, apply tag 1
  • If content contains product name 2, apply tag 2
  • If content contains product name 3, apply tag 3

Why use Conditional tags?

Madcap Flare definition: A condition tag is a marker that you can apply to different areas of your content so that some sections show up in some of your outputs but not in others. It is just one of the many single-sourcing features that you can use in Madcap Flare.

After you create condition tags, you can apply them to the appropriate content in your project.

For example, you can apply condition tags to:

  • Topics
  • Images
  • Stylesheets
  • Skins
  • Files
  • Paragraphs
  • Text within paragraphs
  • Table rows and columns
  • Table of contents (TOC) entries
  • Index keyword markers.

Applying Condition Tags to Online Content

How to apply condition tags to text:


  1. In the Primary Target, click Conditional Text.
  2. For each tag, click the Include or Exclude check boxes.


  1. Open the content.
  2. Select the text to which you want to apply the condition tag.
  3. Select the Home ribbon, Attributes section, Conditions.


If you want to apply a condition tag to selected text in a paragraph:

  • In the XML Editor, select the text.
  • In the Project Organizer, open the Conditional Text folder and expand the condition tag set.
  • Drag the condition tag to the selected text in the XML Editor.
  1. For each condition tag you want to apply, click the check box next to the tag.
  2. Click OK, then Save.

Checking Conditional Text Settings in the Primary Editor

You can tell Madcap Flare to include or exclude content as follows:

  1. Open the Primary Target.
  2. Click Conditional Text.
  3. For each tag, click the Include or Exclude check boxes.


This tells Madcap to apply these settings to the conditional text.

Still doesn’t work?

Check that you have the Show / Hide Conditional Indicator button turned on.


This is on the lower right of the XML Editor. When you turn this on, the conditional tags color code should be displayed.

Now, rebuild the content – does it work?

Hop over to our Facebook Tech Writers page and let us know.

Posted on

5 Part Formula for Writing Error Messages

How can we write error message that are both helpful and human?

Error messages fall into three categories: informational, warning, or errors.

Error Message: 5 Part Format

Most messages contain these parts:

  1. Error number — a one-to-five-digit number that identifies the message. User-defined messages may contain more digits.
  2. Description — a Unicode string that contains information about the condition that generated the message.
  3. Severity level — a one- or two-digit number that indicates the severity of the error condition.
  4. State — a one- to three-digit number with a maximum value that indicates the location in the code that generated the message:
  5. Line number — a number in a stored procedure that contains the statement that generated the message.

For example

Error number: 6696

Severity level: 8

State: 2

Line: 5

Description: Invalid object name ‘ObjectMissing’.

That help?

Stay tuned for the next episode!

Posted on

Madcap Flare – Close all Open Documents Except Active One


Ever want to close all the open documents in Madcap Flare except the one you’re working on?


If so, here’s how you do it:

  1. In Flare, click the Window tab.
  2. In the Open Windows section (far left), click the Close All Documents button. This opens a drop-down list.
  3. Click Close All Documents Except This One.

Now, you can get your workspace in order again and decide which files you want open.


Posted on

How to Write Error Log Messages


You know in Star Trek, when they’re looking into the Captain’s Log? I bet they also had an Error Message log for when things went real bad. You know, like when the Klingons actually won and took over the Enterprise.

Ok, so what’s this got to do with tech docs?

Well, it’s a roundabout way to look at error log messages. They don’t get much love, do they?

If you’re not happy with the quality of your error log messages, see if this helps.

How to Write Error Log Messages

Severity Levels

Error messages fall into the following categories: Error, Warning, or Information.

Define your log messages according to their severity.

  • Error – The error is severe. Immediate action should be taken to avoid the loss or corruption of data.
  • Warning – Action should be taken at some stage to prevent a severe error occurring in the future.
  • Info – An informative message, usually describing server activity. No action is necessary.

Checklist using Cause/Solution Format

Use a cause/solution format when writing the error log messages:

For example:

9968: No port defined for import.


The server cannot detect a port.


Contact Technical Support.

9969: Bulk import not supported.


The server will not accept an import.


Contact Technical Support.

9807: Ignoring large value for new_attribute_name.


The value of the configuration attribute is invalid.


Change the value of the configuration attribute. Refer to the Help files for the acceptable value range.

Checklist for Complex Issues

In some cases, you may want to provide more background details and list the steps to resolve the issue.

6696: Source Not Available


A Source is not available. Last monitoring query showed source is unavailable.


The error occurred because of any of the following reasons:

  • Data source is offline
  • Data source is not responding
  • Network issue


Do any of the following:

  • Bring source back up
  • Fix network issue
  • Bring source down.

… stay tuned for next week’s episode!

Posted on

[Checklist] How to Review Troubleshooting Guides


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

Madcap Flare: Snippets 101


Snippets? Sounds familiar but what are they?

In the Madcap world of Flare, snippets are content ‘fragments’ you can re-use in different parts of your Madcap Flare projects.

Use snippets to insert:

  • Text
  • Tables
  • Images
  • Video

Why Use Snippets

If you find yourself typing the same text over and over, create a snippet instead.


Create the content once instead of re-typing and reformatting it for each topic.

If you want to modify a snippet, change its contents and the text is automatically updated everywhere that the snippet is added.

Snippets are contained in .flsnp files (flare snippets).

You can share them with other authors or use them in other projects.


Default Save location

Snippet are saved in the Content Explorer in the Resources\Snippets folder by default.

However, you can store it anywhere in the Content Explorer that you like.

Creating New Snippets

There are two ways to create a snippet.

  • Create Snippets From Existing Content — If you have already created content and want to use it as a snippet, use the Home ribbon or Format menu. Insert the snippet into other topics where you want it to appear.
  • Add Snippets — Add a new snippet and insert it into the topics.


To create new snippets from existing content:

  1. Open the topic.
  2. In the XML Editor highlight the content that you want to turn into a snippet.
  3. In the Home ribbon, select Create Snippet.
  4. In the Snippet File field, type a new name for the snippet. After the snippet is created, you can see it in the Content Explorer.
  5. If you want the snippet to replace the highlighted text in the topic, select the Replace Source Content with the New Snippet check box.
  6. Click Create. The snippet is surrounded by brackets (if markers are turned on).
  7. Save.

Inserting Snippets

After you’ve created a snippet, you can insert it into a topic.

You can do this by using the ribbon or drag an existing snippet from the Content Explorer or File List window pane.

How to insert a snippet

  1. Open your file.
  2. Place your cursor where you want to insert the snippet.
  3. In the Insert ribbon, select Snippet. The Insert Snippet Link dialog box opens.
  4. Navigate to the snippet that you want to insert and select it.
  5. Click OK. The snippet is inserted and is surrounded by brackets (if markers are turned on).
  6. Save your work.


Editing Snippets

When you edit a snippet, the changes are automatically updated in every topic where you inserted the snippet.

How to edit a snippet

  1. To open the snippet:
  • Right-click on the snippet in a topic where it is inserted and select Open Link OR
  • Locate the snippet in the Resources\Snippets folder in the Content Explorer and double-click it.madcap-flare-snippet-5
  1. In the XML Editor update the snippet.
  2. Click Save.

Did that help?

Did it give you any new ideas on how to create your web help or tech docs? Fess up, stranger.

Oh yeah, we’re over here on Facebook.

Posted on

Review Checklist for Technical Documents


Making a list, checking it twice…

How do you review your technical documents? You just don’t eyeball them, right?

Before you send your shiny new user guide into the wild, use the following checklist to review your technical documents:


Is the title consistent across all documents? Note lower, mixed, and upper case combinations

Product name

Is the name of products consistent?


Does the document adhere to the company style guide?


Is the strapline consistent?


Is the same logo used on all documents?

Cover sheet

Check legacy documents or documents created with a rogue template


Is the same version number used on all documents?

File Properties

If writers use File, Save As to create a new document, the ‘old’ file properties must be updated

Table of Contents

Has it been updated? Have rogue sections crept in?


Are UK and US English used in the same document?


Don’t write what might happen next. Explain what to do right now when you’re performing the procedure.

Instead of:

The command should be run if a new product is installed.


If this product is installed, run this command.


Don’t write what will happen, say what is happening now.


This will create the following files in the Bin subdirectory.


This creates the following files in the Bin subdirectory:

Start with Verbs


The folder located on the D:\ drive should be copied from the server.


Copy the folder located on the D:\ drive from the server


Add a caption and explain what’s happening in the screenshot.

Don’t assume the reader understands what’s happening in the screenshot.

Within v in

Don’t say the chapters within the document.

Within specifies a time frame, for example, within 3 days.


List prerequisites in the correct order.

If you have to install prerequisites in a specific order, use a numbered list. Add warnings, cautions, and recommendations.


In the Upgrade section describe:

  • New install — how to install from scratch, a clean install.
  • Upgrade — how to upgrade an existing installation.
  • Uninstall — how to remove the application from your system. Include any recommendations or warning before they start.

Repeated phrases

For example, if you say that you need to perform the following steps as an Administrator in the first sentence, you don’t need to mention it again.


To install the server, perform the following steps as an Administrator:

Open the Command Prompt as an Administrator.


To install the server, perform the following steps as an Administrator:

Open the Command Prompt.

Posted on

Madcap Flare: Logo Size and Settings for WebHelp


Want to replace the default MadCap Flare logo for your online help?

Before you do, a few things to consider:

  • For IE 6 or older uses — save the logo as GIF with a transparent background. If you use PNG, the transparent portion of your image appears as black.
  • For IE 7 or newer — save the logo as PNG with a transparent background.
  • HTML 5 skin — create the logo 60 pixels high. The width depends how far you want it to stretch across the header.

One suggestion is to create the logo 55 pixels and leave a 5 pixel border to set it off from the other UI elements.

  • HTML 5 DARK skin — use white (or another light color) for the text to contrast with the dark background.
  • HTML 5 LIGHT skin — use… go on, have guess what color? J

Save the image somewhere you’ll remember, for example to your Content/Images folder.

Posted on

How to Create (Stunning) Web Forms


Creating web forms is harder than you’d think. Yes, it looks easy but…

Before I forget — try Formstack if you want stunning-looking web forms.

So, let’s say you’re designing a form for your company’s website.

How can you make sure uses don’t get frustrated, impatient, or annoyed and leave your site?

The last thing you want is to get someone to your site, then see them hit the Back button because one field confused them.

When designing forms, you have (at least) five HTML form elements to play with:

  1. Drop-down box
  2. Radio buttons
  3. Check boxes
  4. Type-in box
  5. Hyperlinks

But which should you use?

It’s the wrong question, isn’t it?

In form design there’s no ‘one size fits all.’

We need to determine which element works best — at each stage in the form design.

Sarah Miller and Caroline Jarrett [PDF] suggest four steps for choosing web form elements:

  1. Is the page for navigation or information gathering?
  2. How will your choice impacts the form?
  3. How will it affect your users and their interactions?
  4. Use these six questions to narrow down the choice of form element for each question on your form.

The six question are…

  1. Is it more natural for the user to type the answer rather than select it?
  2. Are the answers easily mis-typed?
  3. Does the user need to review the options to understand the question?
  4. How many options are there?
  5. Is the user allowed to select more than one option?
  6. Are the options visually distinctive?

You agree with this approach?

Before you leave, can you answer this?

What’s the worst mistake you’ve seen in form design?

What site nails it for form design?

If you had a magic wand, the one thing you’d change….

PS – If you want to design web stunning forms, take the free trial on Formstack.

Posted on

Web Help: 5 Index Guidelines


Do you provide an index for your online documents?

I’m not sure if today’s customers actually want an index. Maybe they prefer to search.

Of course, not everyone agrees with me.

Lori Lathrop, author of An Indexer’s Guide to the Internet, helps firms index their technical publications for software, manufacturing, and science.

She highlights four points when indexing documentation:

  1. Document Type — product documentation, user guide, operations manual, etc.
  2. Terminology — industry-specific, product-specific, and author-specific.
  3. Audience characteristics — background, education, current skills, familiarity with your product or competitive products.
  4. Audience objectives — needed skills, tasks to be performed.

A nice set of guidelines to get us started.

But what about if you’re moving your documents online.

Do you still need to index the content?

Does a good Search function replace the need for an index?

Indexing Online Help

The team at Adobe RoboHelp provides the following guidelines when creating an index for online help:

#1 Prioritize user needs first

  • Focuses on their tasks and way of thinking.
  • Consider their backgrounds and knowledge.
  • Use words and phrases they’re likely to think of when looking for information.
  • Users can and do form impressions about the usefulness and value of a Help file based on their experience with the index – and in this case, perception is reality.

If they can’t locate information in the index, users may doubt whether or not the information exists in the Help file. If users are consistently taken to the wrong topics or to unexpected topics, they may doubt the accuracy of the Help file.

#2 Index the most important words

  • Include only those words and phrases your users are most likely to look up.
  • You don’t have to index every word or phrase – like “About” or “Working with.”
  • For ideas on good index entries, look at the features and content of your Help system – topic titles, headings, tables, examples, and so on.
  • Include terms commonly used by both beginners and experts.

#3 Provide multiple ways to access the same information

  • As user may not be familiar with the terms and concepts used in your Help system, provide synonyms and alternate index entries.
  • Include verbs, noun phrases, and synonyms to reach the widest range of users.
  • Index your competitors’ terms, too – users may not know the name of the feature in your Help system, but they might know what it’s called in your competitors system.

#4 Use consistent access routes

  • Use consistent phrasing throughout the index.
  • Include inverted terms and headings – what the command is as well as what the command does.

This approach helps users find information regardless of whether they’re looking for the command or the action the command accomplishes. (For example, Printing:Landscape, Landscape:Printing.)

#5 Provide enough detail for users to choose

  • Provide enough description with your index entries so users can determine which path to choose.
  • Users should be able to tell the difference between index entries that lead them to conceptual overviews and entries that lead them to tasks.

I’m still in two minds about creating an index. What do you think?

Is providing an index a thing of the past?

Do users prefer a search engine to an index instead?

Posted on

Madcap Flare: how to improve Search Engine Optimization


Using Madcap Flare to create your WebHelp? Did you know you can add SEO information to the page headers? This improves their results in search engines queries and helps customers find information faster.

Want to know how? Follow these steps, grasshopper.

Madcap Flare: how to improve Search Engine Optimization

  1. In Project Organizer, click Targets, then open your target, for example, HTML5.
  2. In the Tag Editor, click Advanced.
  3. Click the Generate Site map check box. Enter the path to your site map.
  4. Click the Include importance check box. Select the number of results per page to appear and the abstract character limit.

Publish and check that the site map is included in the HTML output.

Madcap Flare: how to add meta tags to HTML5 and Web Help


You can add meta tags to your web files:

  1. In Project Organizer, click Targets, then open your target, for example, HTML5.
  2. In the Tag Editor, click Advanced.
  3. Click the Add meta tags to content check box.
  4. Enter the meta tags in the text box.

Publish and check that the meta tags are included in the output.

Madcap Flare: how to change the default logo

You can change the default MadCap logo that appears on the top left of HTML5 outputs.

You can remove the logo or replace it with your own logo:

  1. In Project Organizer, click Skins, then open your skin, for example, HTML5.
  2. Click Styles (second from end).
  3. In Global, click Main Page, Background, Image.
  4. Browse to your image and insert it.
  5. Click Preview to test how it looks.

If necessary, change the image size.

A second approach is as follows:

  1. In Project Organizer, click Skins, then open your skin, for example, HTML5.
  2. Click Styles.
  3. In Header, click Logo, Image.
  4. Browse to your image and insert it.
  5. Click Preview to test how it looks.

If necessary, change the image size.

Note: You can also add a Site Map as shown below.


Madcap Flare: how to enter the Title tag

The title tag is one of the most important

  1. In Content Explorer, right-click on your file, then click Properties.
  2. In Topic Properties, click Topic Title.
  3. Enter the title tag.

Publish and check that the title tags is included in the HTML output.



Posted on

Madcap Flare: How to Create Variables


Are you using variables in your technical documents?

If not, you might be missing out. They save a lot of time and help keep the documents accurate, for example, if you need to change a product name across the entire doc set. If those puppies were hard-coded, you’re in trouble.

We use Madcap Flare. The procedure is more or less the same in FrameMaker or Robohelp.

Creating variables in Madcap Flare

To create a variable:

  1. Open the Project Organizer.
  2. Click Variables. As it’s V it’s at the end of the list.
  3. Double click on General to open the Variable Set Editor.


Here you can add, edit, and delete variables.

Adding variable definitions in Madcap Flare

  1. Click Add Variable Definition.
  2. In the Edit Format window, enter the specifiers.
  3. In Update, select when it will be updated, for example, on file creation, save, or build.


 That work for you?

Posted on

How to Remove the MadCap Logo in WebHelp Output


When creating WebHelp with Madcap Flare, you can add your own logo instead of the default Madcap logo.

Here’s how to do it.

To remove the MadCap logo and replace it with your own logo:

  • Open the skin want to remove the logo from.
  • Click the Styles
  • On the Tool Item category, click Logo.


  • Click the General category in Logo.
  • To remove the logo, click on the image path and select None.
  • To add your logo, click on the image path and select your image.

If you’ve any questions about this. contact us on our Facebook Technical Writing page.