Posted on

MadCap Flare: Conditional Text 101

madcap-flare-conditional-text

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:

First:

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

Then:

  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.

madcap-flare-conditional-text-2

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.

madcap-flare-conditional-text

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.

madcap-flare-conditional-text-3

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 2 Comments

Do Technical Writing projects need a Documentation Plan?

Gordon McLean asks: do you plan to review your plan?

This is in relation to the Documentation Plan (aka Information Development Plan) that most technical writers prepare in advance of starting a major project. Granted, on smaller projects you can get away with this if you know the product, have the resources and the deliverables are nailed down.

But, his point is that the plan itself should be reviewed/updated during the project lifecycle. Or, at least, that’s how I read it. Continue reading Do Technical Writing projects need a Documentation Plan?

Posted on

Documentation Plan: How to Get Started

Preparing a Documentation Plan involves several different activities. Depending on the complexity of the project you may want to change the depth of the plan, but most plans will include:

    1. Overview
    2. Resource Requirements
    3. Schedule
    4. Deliverables

Tip: Documentation plans are also known as Information Development plans.

planning-raidIn this article, we’ll look at Resource Requirements and Scheduling.

Creating a documentation plan involves scoping resource requirements and scheduling the individuals involved in information development activities.

Before you get into the actual planning, some things to consider are:

    • Can the existing documentation set be reused?
    • Does it require updating or revising?
    • Have the current tech writers worked on the previous doc set?
    • Do you need to hire and train new writers?
    • Do you have a budget / daily rate for these writers?
    • Is the solution you’re planning to document ready?
    • If not, is it sensible to start documentation?

Deliverables

List the deliverables that you will provide. Highlight if any of these are critical and/or mandatory for the solution’s delivery.

    • Admin Guide
    • Online Help
    • Product Guide
    • Release Notes
    • User Guide

You may want to expand on these and describe the document format (Word, PDF, HTML), estimate page count, estimate graphic requirements.

Estimating Costs

When estimating the associated costs for this project, consider the following factors:

    • Who is responsible for non-writing tasks, for example, translation, production, circulation etc.
    • Will Subject Matter Experts and Users need to be interviewed? If so, when and where? Are there additional costs in performing these activities, e.g. travel expense?
    • Will tech writers need to attend training sessions and/or workshop in order to understand the software?

Identifying Resources Requirement

To plan successfully, you will need to capture all resources that will be required throughout the project lifecycle. At first glance, most of us think of the human resources required. That’s the writers, editors and programmers.

But you also need to work out what software, hardware, security, passwords, and other resources you may need.

First up, identify all individuals involved in producing the document, not just those involved in writing activities.

    • Graphic Designers
    • Human Interface Designer
    • Information Architects
    • Product Manager
    • Programmers
    • Software Manager
    • Technical Editors
    • Testers
    • Web Designers

Identify how many person months from the [start date] to [end date] are required for the project. This helps estimate costs involved in producing the documents, especially if you need to localize material

Hardware

Identify the hardware requirements, for example, access to servers with sufficient memory and disk storage for running Adobe FrameMaker, Visio and DITA authoring tools simultaneously.

You may also need access to servers to test and verify your documents.

Software

Identify the software required for content development:

    • Adobe Acrobat
    • Adobe FrameMaker
    • Adobe PhotoShop
    • Camtasia SnagIt
    • Madcap Flare
    • Microsoft Visio
    • Microsoft Word

Writer’s requirements

Describe the writer’s requirements, for example:

  • Access to documentation and specifications
  • Access to test system for verification
  • Access to subject matter experts

Project Scheduling

Outline the project’s goals and reporting structure. After this, identify your assumptions and dependencies.

If these are NOT met, the project is at risk and unlikely to meet its objectives.

Assumptions

Examples of assumptions for an IT project include:

    • Changes to schedules will effect the delivery dates
    • Changes to resources will impact the quality of products as new hires will have to be skilled up
    • Changes to specifications will mean that content will have to be reevaluated and adjusted accordingly.
    • Reviewers will be available and provide feedback on schedule.

Dependencies

    • Examples of dependencies for an IT project include:
    • Availability of Subject Matter Experts
    • Availability of system, network access, password, physical access to buildings if required, access rights
    • Access to specifications, project plan, test scripts as required
    • Review and feedback is received on time

That’s most things. Let me know if you need direction with yours.