Quick Guide
Version 4.0
Scan this QR code to open the
online Help on your mobile device.
Copyrights
Copyright 2011 MadCap Software. All rights reserved.
Information in this document is subject to change without notice. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used
or copied only in accordance with the terms of those agreements. No part of this publication may be
reproduced, stored in a retrieval system, or transmitted in any form or any means electronic or
mechanical, including photocopying and recording for any purpose other than the purchaser's personal use without the written permission of MadCap Software.
MadCap Software
7777 Fay Avenue
La Jolla, California 92037
858-320-0387
www.madcapsoftware.com
Contents
CHAPTER 1 Introduction
About the MadCap Feedback Explorer
1
2
CHAPTER 2 Getting Set Up with MadCap Feedback
3
CHAPTER 3 Features
5
Feedback Files
Administrators
Topics
Topic Ratings
Comments
Search and synonyms
Exporting
5
5
6
6
7
9
10
Index
11
-i-
MADCAP FEEDBACK
- ii -
CHAPTER 1 Introduction
Welcome to MadCap Feedback and MadCap Feedback Explorer, which let you track live user feedback on your MadCap Flare online documentation—not only for Web-based output, but also for desktop output such as Microsoft HTML Help and DotNet Help.
Feedback is a live documentation reporting service that works in conjunction with Flare to provide
Web 2.0 community benefits for your online output—including integrated user comments and statistics such as search keywords used and topics visited. Most of these benefits are available not only
for Web-based Help (i.e., WebHelp and WebHelp Plus), but also for desktop Help (i.e., HTML Help
and DotNet Help).
You have two options when setting up Feedback.
n
Feedback Server With MadCap Feedback Server, you install the necessary software on your
own hardware to host the Feedback data. By using the MadCap Feedback Server Admin, your
system administrator can enter the appropriate server information, create the necessary SQL
database, and perform maintenance tasks such as scheduling automated backups of the data.
Authors can use the Feedback license keys that are issued as needed for their various targets
and projects. The Flare output files can be hosted on the same server hosting the Feedback
data, but it is not mandatory; the output files can be published anywhere you like.
n
Feedback Service With MadCap Feedback Service, there is no need to purchase your own
hardware or host the Feedback statistics. MadCap Software does the hosting for you. This
does not mean, however, that you publish the output files to MadCap Software's server.
Instead, you publish the output files to your own server or anywhere else that you choose.
Even if you have attached your online output to a desktop application, you can still take
advantage of the Feedback features. The number of Feedback license keys issued depends on
the number that you purchase.
-1-
MADCAP FEEDBACK
About The MadCap Feedback Explorer
Feedback Explorer provides an interface that is used to view and track all reader activity in your
online output. This is a standalone application that is separate from Flare. It displays user activity
for the most recently opened Feedback file (which is associated with a target/license combination in
Flare).
The following diagram illustrates how Feedback Explorer works with MadCap Feedback and MadCap Flare output.
-2-
CHAPTER 2 Getting Set Up With MadCap Feedback
Getting set up to use MadCap Feedback involves the following basic steps. For more information see
the online Help or the Getting Started Guide.
1. Install MadCap Feedback Server This step needs to be completed only if you have purchased the MadCap Feedback Server (as opposed to the MadCap Feedback Hosting Service).
Provide your system administrator with the instructions that are necessary for installing the
software and other components.
2. Configure Feedback Server Admin This step needs to be completed only if you have purchased the MadCap Feedback Server (as opposed to the MadCap Feedback Hosting Service).
Provide your system administrator with the instructions that are necessary for configuring the
MadCap Feedback Server Admin. This includes the ability to require a password for Feedback
Explorer access, test settings, set up an SMTP server for email notifications, specify redirection Web pages for end users who register, and schedule automatic backups of the database and transaction log.
3. Install Feedback Explorer Each user on your team who plans to use Feedback Explorer to
view user comments and statistics should install this software locally. This includes managers who do not use Flare but want to be kept informed about user activity on the published
output.
4. Obtain Feedback license(s) You need a separate Feedback license for each Flare target
that you want to track. After you purchase the MadCap Feedback Server or Service, you will
be issued the appropriate Feedback license(s) from MadCap Software.
E X AMPLE
Let 's say y ou hav e t hree au t hors and a manager on y ou r t eam. You hav e a
t ot al of fiv e d ifferent Flare p roject s, and from each of t hose p roject s, y ou and
t he ot her au t hors are generat ing t wo online t arget s. So as a t eam, y ou are p rod ucing a t ot al of t en online ou t p u t s (t wo t arget s each from fiv e p roject s). How
many Feed back licenses are need ed so t hat t he au t hors and manager can t rack
t he u ser act iv it y for all of t hose t arget s? In t his case, y ou wou ld need t en
licenses (one for each ou t p u t t hat y ou want t o t rack).
.
-3-
MADCAP FEEDBACK
Note: It is possible to use the same Feedback license for different Flare targets. However,
you must keep in mind that the statistics for the various targets will then become merged
when you view them in Feedback Explorer. You will not be able to determine which statistics resulted from which targets.
5. Enable Feedback in Flare targets After obtaining the necessary Feedback license(s), you
need to enable the Feedback functionality in Flare. This is done on the Feedback tab in the
appropriate targets. For more information see the Flare online Help.
6. Configure Flare target with Feedback Explorer One of the first tasks that must be performed in Feedback Explorer is to create or open a file that is configured with a target in MadCap Flare. You can initialize this task from Feedback Explorer or from within Flare. It is
easiest to create and open the initial Feedback file from within Flare. The reason for this is
that you only need to enter your Feedback license once. After entering the license key in
Flare's Target Editor, simply click the button labeled Configure with Feedback Explorer
Application.
7. Enable comments in the skin If you want end users to be able to enter Feedback comments in the online output, you need to enable comments. This is done by opening the skin
in Flare that is associated with the target, selecting the Feedback tab, and clicking Display
topic comments at the end of each topic. For more information, see the online Help in
Flare.
Tip: If you want to test the Feedback Server or Service against your output, you can easily do so
by first using a Feedback license in an unpublished target. After testing Feedback for that output,
you can clear the Feedback database and remove the license from your test target. All Feedback
data (including all comments, topic ratings, and search queries) will be removed from the database. Then you can add the license to the target that you intend to publish and distribute the output to end users. (It is also a good idea to clear the cookies from your Internet browser.)
-4-
CHAPTER 3 Features
Feedback Explorer offers an extensive list of features to assist you in working with Feedback. Following are some of the key features that make Feedback Explorer unique.
Feedback Files
Feedback files are the primary files that allow you to view how people are using your output.
n
Creating and opening Feedback files One of the first tasks that must be performed in
Feedback Explorer is to create or open a file that is configured with a target in MadCap Flare.
You can initialize this task from Feedback Explorer or from within Flare. It is easiest to create
and open the initial Feedback file from within Flare. The reason for this is that you only need
to enter your Feedback license once. After entering the license key in Flare's Target Editor,
simply click the button labeled Configure with Feedback Explorer Application.
However, some individuals may want to perform this task from Feedback Explorer. For example, some people (such as managers) may not work in MadCap Flare, but want to track user
activity in the author's online documentation files.
After the configured Feedback file is open, there are several things you can do to view and
track user activity for a Flare target.
Administrators
You can specify individuals, called administrators, who should be emailed when events such as the
following take place: users submit new comments that require acceptance before they are published
(see page 1), the status for a comment is changed, searches are performed with no results, topics are
rated, and context-sensitive Help (CSH) calls are made. Administrators can also be subscribed to an
email manifest, which automatically emails summaries of Feedback activity periodically. An administrator might be a writer on the documentation team, or even an individual such as a manager or
documentation leader who will not necessarily take action on user activity but still needs to be kept
informed. Each administrator can be set up to receive different types of emails.
Note: It is not mandatory that you add administrators. It is simply an activity that helps speed
the process of accepting new comments and performing other tasks, because it notifies the appropriate individuals when action may need to be taken. Anyone who has Feedback Explorer
installed with the appropriate Feedback license key will be able to take action, such as accepting
pending comments, even if they are not added to the administrator notification list.
.
-5-
MADCAP FEEDBACK
Topics
You can view lists of all topics opened by end users, as well as topics associated with context-sensitive Help IDs.
n
Viewing topics visited You can use the Topics window pane to view a list of all the topics
that users have opened in your output. This includes a count of how many times each topic
has been opened, as well as its average rating from users and the number of comments that
have been submitted.
n
Viewing topics visited (CSH calls) You can view all of the topics that users have opened
through context- sensitive Help (CSH) calls that you integrated into your output. This
includes each CSH ID, the topic it points to, and the number of times it has been accessed.
Topic Ratings
With MadCap Feedback, users can give a rating to a topic, selecting from one to five stars. You can
then view these ratings (which are displayed as a numerical score from 0 to 100) and make adjustments to the topics as necessary.
-6-
n
Rating topics (users) Learn how users submit ratings for topics in your online output.
n
Viewing topic ratings After users enter ratings for topics, you can view them in Feedback
Explorer.
CHAPTER 3 Features
Comments
Users can enter comments on your online topics. These comments may be viewed (and replied to) by
all other users viewing the output.
n
Controlling which comments are added to the output As the author, you have control over whether new user comments should be reviewed before they are displayed in the
online output. If you specify that all incoming comments require review, those comments will
have Pending status until you take action on them (e.g., accepting, discarding, hiding). If you
specify that reviewing comments is not necessary, all incoming comments will automatically
move to Accepted status and become immediately visible in your online output. You can
always change the status of a comment, thereby affecting whether it is visible and to whom.
n
Enabling anonymous comments When users submit comments, they may be required to
register, providing information such as user name, email address, and more. However, you
can set up a Feedback file so that anonymous users will be accepted. In that case, users will
not need to register; instead, they simply enter any user name when submitting a comment.
n
Entering comments (users) Learn how users submit these types of comments from your
online output.
n
Viewing all comments After users enter comments, you can view them in Feedback
Explorer. This can be done from the Comments window pane, which can be accessed by selecting View>Comments. Initially all comments are displayed. However, you can use the filter
drop-down in the local toolbar to narrow which types of comments are shown (e.g., Accepted,
Pending, Hidden).
n
Accepting pending comments If you set up MadCap Feedback so that new comments
require approval before being added to the online output, those comments move to Pending
status by default. Therefore, you must accept a comment before it is added to the online output to be viewed by everyone. Even after you accept a comment, you can later change your
mind and assign a different status to it (Hidden, Pending Review) or discard it any time you
want.
n
Hiding comments If you do not want a comment to be visible to all users in the community, but you also do not want to delete it from the system, you can change its status to
Hidden. That way, you can continue to access the comment in Feedback Explorer, but end
users will not see it in the online output. You can assign a different status to it (Accepted,
Pending Review) or discard it any time you want.
n
Editing comments From the Comments window pane you can modify a comment's subject, status, and text. For example, you might use this feature if you misspell a word in your
reply to a reader's comment. This allows you to correct your mistake after the fact.
n
Setting comments to Pending status If you set up MadCap Feedback so that new comments require approval before being added to the online output, those comments move to
Pending status by default. This means that the comment is visible only to you and the end
user until you accept it. If at any time the comment has a different status than Pending (i.e.,
Hidden, Accepted), you can apply the Pending Review status to it.
-7-
MADCAP FEEDBACK
n
Discarding comments If you do not want to keep a comment in the system, you can permanently delete it at any time. After you do this, you will no longer be able to access the comment.
n
Replying to comments After you receive comments from users, you can reply to them. You
can either obtain the individual's email address and send a private response, or you can reply
to the user from the online output so that everyone in the community sees your response.
When you reply in the output, you can do so in two different ways. The easy way is to reply
from a notification email you receive. Otherwise, you need to navigate in the output to the correct topic and reply from there. If you reply to new comments from an email notification that
you receive, you do not need to go through the process of accepting that comment, or your
own comment for that matter. When you reply to a comment from the email link, not only is
a reply created, but the original comment and your reply comment are approved at the same
time.
n
Viewing active users You can view a list of active users for your online output. In other
words, the list shows the users who have registered and submitted at least one comment.
Note: If you want end users to be able to enter Feedback comments in the online output, you
need to enable comments. This is done by opening the skin in Flare that is associated with the
target, selecting the Feedback tab, and clicking Display topic comments at the end of
each topic. For more information, see the online Help in Flare.
.
-8-
CHAPTER 3 Features
Search And Synonyms
With MadCap Feedback, you can determine how readers are using search in your online output.
This helps you answer questions such as: What are they looking for? What are they finding? And
more importantly, what are they unable to find? You can use Feedback Explorer to view all used
search phrases, as well as searches where no results were returned to the user.
n
Viewing used search phrases You can see statistics on all search phrases used, including
the number of searches performed for each term and the number of results returned for users
each time. This lets you know the information that users are seeking most often. You can then
make the necessary adjustments to your project, such as adding more details to the appropriate topics.
n
Viewing searches without results You can see statistics on the search phrases for which
users did not find results, including the number of searches performed for each term.
n
Creating synonyms If users enter search phrases in your online output and those phrases
are not returning results, this does not need to be the end of the story. You can make improvements to your output so that, in the future, users are able to find the search results they need.
One way to make an enhancement is to add the information that your users are looking for (if
that information does not yet exist in your Flare project). Another way to enhance your output is to create synonyms for search phrases.
You can create synonyms within the Flare project or within Feedback Explorer. It is not mandatory that you have Feedback in order to use synonyms in Flare output, but using Feedback
makes it much easier to determine which words require synonyms based on the search results
of your users. Using Feedback Explorer to create synonyms is appealing because the synonyms become immediately available for users searching in your output (without needing to
republish the output). Be aware, however, that creating synonyms in Feedback Explorer
works for the Feedback output as long as you continue to publish output to the same server.
If you create synonyms in Feedback Explorer, it is recommended that you also create those
synonyms at the source (i.e., within the Flare project), in case you ever publish to a different
server. The easiest way to do this is to export your synonyms to that Flare project.
E X AMPLE
Let 's say t hat y ou v iew search key word resu lt s from y ou r u sers and find t hat
many are ent ering t he search t erm "sofa. " Unfort u nat ely , y ou hav e not u sed
t hat word in y ou r p roject , so u sers are u nable t o find t he t op ics t hat t hey
need . Howev er, y ou hav e u sed a similar word , "cou ch. " Therefore, in t he Sy nony ms Ed it or, y ou ent er "cou ch" as a sy nony m for "sofa. " The next t ime a
read er ent ers "sofa" as a search key word , t op ics cont aining t he word "cou ch"
will be ret u rned in t he resu lt s.
Note: This feature is available if you are generating DotNet Help, WebHelp, or WebHelp
Plus output formats only. It is not available for HTML Help output.
.
-9-
MADCAP FEEDBACK
Exporting
You can export data in the following ways.
- 10 -
n
Exporting data to Microsoft Excel (using a CSV file) AfAfter you accumulate data in
Feedback Explorer, you can export it to a comma-separated value (CSV) file. You can then
open the file in Microsoft Excel.
n
Exporting data to a tab-delimited text (TXT) file After you accumulate data in Feedback Explorer, you can export it to a tab-delimited text (TXT) file.
n
Exporting synonyms After creating synonyms in Feedback Explorer, you may want to
export the synonyms file (MCSYNS) to another location. Those synonyms can then be added
to the Flare project associated with the Feedback file, or even a different Flare project.
Index
A
M
Active users
8
Administrators
5
C
Comments
accepting
active users
discarding
editing
hiding
MadCap Feedback
pending
replying
reviewing
status
CSV file
7
8
8
7
7
3
7-8
8
7
7
10
MadCap Flare
enabling comments
enabling Feedback
MCSYNS file
10
Microsoft Excel
10
P
Pending comments
Ratings
10
10
S
Search
Accepted
Hidden
Pending Review
Synonyms
F
exporting
Feedback
Feedback Explorer
Feedback Explorer
2
2-3
4-5
10
7
7
7
9
10
T
Tab-delimited file
comments
visited
TXT file
L
Licenses
9
10
Topics
Files
Feedback
6
Status
Exporting
Feedback data
synonyms
7-8
R
synonyms
E
4
4
3
4
6
10
W
Web 2.0
1
- 11 -
Index
- 12 -