Posted on

MadCap Flare: How to Update Stylesheets

madcap-flare-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.

Interested?

madcap-flare-style-1

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:

Simplified

Advanced

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

madcap-flare-style-5

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.

madcap-flare-style-4

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.

madcap-flare-style-3

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.

madcap-flare-style-2

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

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

madcap-flare-close-open-documents

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

Yes?

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.
    madcap-flare-close-open-documents-1
  3. Click Close All Documents Except This One.
    madcap-flare-close-open-documents-2

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

 

Posted on

How to Write Error Log Messages

error-log-messages-how-to-write

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.

Cause:

The server cannot detect a port.

Solution:

Contact Technical Support.

9969: Bulk import not supported.

Cause:

The server will not accept an import.

Solution:

Contact Technical Support.

9807: Ignoring large value for new_attribute_name.

Cause:

The value of the configuration attribute is invalid.

Solution:

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

Description:

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

Cause:

The error occurred because of any of the following reasons:

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

Solution:

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

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

Review Checklist for Technical Documents

teechnical-documents-review-checklist

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:

Title

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

Product name

Is the name of products consistent?

Branding

Does the document adhere to the company style guide?

Strapline

Is the strapline consistent?

Logo

Is the same logo used on all documents?

Cover sheet

Check legacy documents or documents created with a rogue template

Version

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?

Language

Are UK and US English used in the same document?

Should

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.

Write:

If this product is installed, run this command.

Will

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

Incorrect

This will create the following files in the Bin subdirectory.

Correct

This creates the following files in the Bin subdirectory:

Start with Verbs

Incorrect

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

Correct

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

Screenshots

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.

Prerequisites

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.

Upgrade

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.

Incorrect

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

Open the Command Prompt as an Administrator.

Correct

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

madcap-flare-logo-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

web-forms-how-to-create

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

Madcap Flare: how to improve Search Engine Optimization

madcap-flare-search-engine-settings

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

madcap-flare-search-engine-1

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-search-engine-2

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.

madcap-flare-topic-properties-1

 

Posted on

Madcap Flare: How to Create Variables

madcap-flare-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.

madcap-flare-variables-1

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.

madcap-flare-variables-2

 That work for you?

Posted on

How to Remove the MadCap Logo in WebHelp Output

madcap-flare-remove-logo

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.

madcap-flare-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.

Posted on

Configuration Guides: How To Document Parameters

Configuration-Guides-how-To-Document-Parameters

So, you want to document the parameters for your new Configuration Management Guide.

Where do you start?

Here’s a checklist of what you need to capture when documenting parameters in technical documentation:

Parameter Name

Specify the name of the parameter with consideration to case sensitive naming conventions. Likewise, use the correct format and styling when entering parameters to your documents.

configuration-management-plan-template

Download the Configuration Guide Template here.

 

Location

Specify where in the configuration file that parameter is located. For example, is it part of a specific parameter set or a section of common parameter setting?

For example: This table describes the Log parameters of the Common section:

In this case, the Log parameters are part of a common set of parameters used by the service, server, or application.

Purpose

Describe the benefit to the user when this parameter is configured. Outline what it enables them to achieve and, if necessary, any downstream impacts. For example, if you turn on this option, other options are made unavailable.

However, make sure you provide enough information for the user to understand the parameter’s purpose and also how this impacts other parts of the system, for example:

Defines a locally stored backup license file. This provides protection against interruptions occurring if the connection to the license server is lost.

Prerequisites

Describe if this parameters activities are impacted by other parameter settings, for example:

Defines if a new log file is created at the time specified by the Time parameter or when the current log file reaches the size specified by the Size parameter.

A second example is if the settings are enabled if another setting is set to a specific setting in a different parameter, for example:

Defines if messages are filtered according to the Filters parameter if the Verbosity level is set to comm.

Options

Describe the parameter options is the settings are turned on or off. For example, state which options are available and then describe the settings.

  • True – describe what occurs if the True setting is selected, for example, enables statistics support.
  • False – describe what occurs if the False setting is selected, for example, disable statistics support.

Default value

Some parameters come with a default value, for example, 0, 1, Yes or No. Specify the default value so it’s clear to the reader if they need to change the setting or leave it in its default status.

Use the following phrasing: This is the default value.

Impact

Highlight if this setting impacts other parts of the system, for example, it overrides another parameter’s settings, disables another feature, or impacts the performance of the system.

Related documentation

If necessary, direct the reader to other sources of information which may help them understand the parameter a little better. For example, if it impacts another module or system.

Mandatory

State if the parameter is mandatory.

Note – identify any recommended settings or values which must be set for the parameter to function correctly, for example:

The value of the parameter must match the value specified for the Metrics parameter.

Minimum Settings

A second example is if the parameter must be set to a specific setting, for example:

The value of the parameter must be equal or greater than the value of the TimePeriod parameter.

Multiple values

For some parameters, you can specify a default value, for example, 1000 but also highlight other possible settings, for example:

The default value is 1000. The following values can also be defined:

  • 0 — no data is sent to the server.
  • 1 — data is sent to the server as soon as it is collected. This value reduces performance.

How to document parameters

Describe the parameter settings as follows:

The first sentence describes the purpose of the parameter in a single sentence.

The second sentence describes the available options and highlights the default settings, for example:

The following options are available:

  • True — enables statistics support
  • False — disables statistics support. This is the default value.

State if the parameter is mandatory. Use the following phrasing:

This is a mandatory parameter.

Summary

The skill in documenting parameters in technical documentation is to describe both the parameter and how it affects other settings, modules, or applications.

This means, as a technical writer, you need to understand how it connects to other parts of the system.

Without this knowledge, your documentation may be adequate but not help the reader understand its impact on other products.

PSDownload the Configuration Guide Template here.

Posted on

How to Find Broken Links in Madcap Flare

madcap-flare-broken-links

Tired of all those pesky broken links in your WebHelp projects? Wish they’d go away? Well now you can!

If you use MadCap Flare to create your web help, you can run a broken link checker.

It’s not perfect. But it will catch most dead links, which is a start.

Finding broken links in Madcap Flare

To find broken links:

  1. Click the Project Analysis
  2. Select Broken Links from the drop-down list.

madcap-flare-broken-links

The results are displayed in the Broken Links window.

 

Posted on

Madcap Flare: How to add The Mark of The Web

madcap-flare-mark-of-the-web

Using Madcap Flare for WebHelp?

If you have problems getting Internet Explorer to run web help pages, added ‘Mark of the Web’ to your WebHelp files.

Madcap Flare: How to add Mark of the Web

You can add the Mark of the Web to HTML files so they run locally in Internet Explorer.

  1. In Project Organizer, click Targets, then open your target, for example, HTML5.
  2. In the Tag Editor, click Advanced.
  3. Select the Insert Mark of the Web check box.

PS – Join our Technical Writer’s page on Facebook.

 

Posted on

How much can you make as a technical writer?

Right now, the average aalary of Technical Writing Job in the USD (May 13, 2015) is…

low end 45k

middle earners 90k

high end        135k

Here’s a fuller breakdown:

Engineering Technical Writer$54,000
IT Report Writer$69,000
IT Technical Writer$74,000
Senior Proposal Writer$80,000
Technical Proposal Writer$69,000
Technical Writer$123,000
Technical Writer Contract$61,000
Technical Writer Editor$64,000
Technical Writer Illustrator$39,000
Technical Writer Scientific$61,000
Technical Writer Senior$64,000

You can get the full details at: http://www.indeed.com/salary/Technical-Writer.html