list of each blurb tagged with a condition

[pdenchfield]

I would like to generate a list of each blurb in the output that is tagged with a condition. The purpose is requirements traceability. I imagine this is a common need for technical writers. Any suggestions out there?

condition-tags-for-list.png

list-of-proxy-example.png

[Psider]

If you need it specifically in the output, I don't think that's possible. But you should be able to run a report that lists topics and folders that have a condition applied.

Have a look at Project Organizer > Reports > Right-click Add Report File

[ChoccieMuffin]

You could do it with a separate target, where you exclude all conditions EXCEPT the condition you want to list. Would that help?

[pdenchfield]

Thanks for the ideas.

Maybe I should approach the problem differently - maybe a list of conditioned items is too limiting a notion. What I want to do is generate a compliance copy of the user guide or other document that indexes each requirement. I'm sure this is a common task for technical writers, especially in highly regulated industries such as medical devices. How is this task achieved with Flare?

[Rene Severens]

Hi,

This will not help generating a solution. But in designing the documentation, why are the requirements inside the user guide? For the very complex product I am writing documentation for, a separate Requirements document is used.

Greetings,
René Severens

[pdenchfield]

Thanks for your question, René.

The requirements are in a separate document. Only the requirement identifiers are noted in the user guide.

For example, see the following snapshot. The identifier is the "CR" number at the end of paragraph. This CR number is conditionally tagged to be removed from the final draft to be distributed to customers. The snapshot below is from a "compliance" copy (this condition tag is included in the output). The goal is to help staff in compliance and regulatory find the identifiers in the user guide and thus locate the associated information satisfying the requirement.

req-traceability-example.png

What I want to do is list each identifier and its page number(s), as in a table of contents.

For example:

CR356296 ..... 5
CR555555 ..... 11
SRD30987 ..... 6

(It would be nice to order the identifiers alphabetically, but ordering by page number would be acceptable.)

[Rene Severens]

Hi,

Just a wild idea:

Maybe you can use an index option for this, labeling the requirement identifiers as a keyword and using a format to add the pagenumber?

Greetings,
René Severens

[pdenchfield]

Good idea, René! I think you're on to something. I'll report back in a few days.

[doc_guy]

Oh! That's what you want.

Using index entries is trying too hard!

You want to create a blank topic and use a List-of Proxy.

When you insert the List-of proxy into your topic, Flare asks you to identify the style (and optionally class) that you want to list in this topic.

Add that topic (probably as an appendix?) to your project, and generate output.

You'll get a list of all the times the style is used, and in printed output you'll get a page number as well.

[pdenchfield]

Hi Paul, Thanks for the idea, but the requirement identifiers are currently tagged as conditional text only. To follow your approach, I would need to use styles instead of (or in addition to?) conditions to tag requirement identifiers. I guess I could change my tagging approach and define the style not to appear, but then I'd need a different stylesheet to show requirement identifiers in the output. Looks like I have the following possibilities for tagging requirement identifiers so far:

Conditional text.
>> To hide or show in output (compliance draft vs. final publication), include/exclude condition via target
>> To list each requirement identifier with page number, **unknown**

Index entries.
>> To hide or show in output (compliance draft vs. final publication), configure index to exclude index class "compliance" and configure compliance index to include only that index class (I think - haven't tested this)
>> To list each requirement identifier with page number, create a conditionalized index pointing to index entries of the "compliance" class only

Style tags. (probably span tags)
>> To hide or show in output (compliance draft vs. final publication), create separate CSS for compliance drafts that shows the tag; configure default CSS to hide the tag
>> To list each requirement identifier with page number, create a conditionalized list-of proxy pointing to that style tag

[doc_guy]

You're right. That's too bad. I was hoping they were in there with a span class, but they've used proprietary XML to make that work, and when I tried to hack the List-of proxy, it requires a class element to work properly, and conditions don't use classes either.

Dang. I'm sorry!

You could use find and replace to search for:

Code: Select all

<MadCap:conditionalText

and replace with:

Code: Select all

<span class='condition'><MadCap:conditionalText

Then search for

Code: Select all

</MadCap:conditionalText>

and replace with:

Code: Select all

</MadCap:conditionalText></span>

You'd want to do this on a duplicate version of your project to make sure it doesn't bring the whole thing to its knees, but that would quickly give you a span class you could use for the List-of proxy.

[pdenchfield]

Thanks, Paul. Great idea! Thanks for the detailed guidance.

What would you recommend for showing or hiding the span class? I need to create a new CSS medium, correct?

(wish I could use conditions and show/hide via target instead....)

[doc_guy]

In my example, you will have both conditions and spans. So you can continue to exclude the conditions. The span classes are just there to allow you to use the List Of proxy.

[pdenchfield]

Aha. Thank you, Paul!