Tuesday, May 12, 2020

MadCap Flare 2020 – My Favorite New Features


MadCap Software recently released MadCap Flare 2020 and the May 2020 version of MadCap Central. As with past releases, the new features run the gamut from the unexpected and powerful to those that add convenience. In this review, I’ll touch on a few of my favorite features in this release of Flare. (For a look at all the new features, see the What’s New webinar that MadCap is presenting on May 13 (and likely to be found soon afterwards at MadCap’s web site).

Micro Content Enhancements

The biggest change is an enhanced micro content feature. MadCap Software has added support for conditions on micro content phrases in order to control what phrases are available for a given output. It also added support for conditions to control what micro content is seen when viewed in normal topics or as search results. Finally, it added support for variables in micro content, similar to “regular” variables. The result effectively creates a new development stream that can be used in parallel with regular topics or even in place of regular topics. If you’re already familiar with conditions and variables, using them with micro content won’t be too big a challenge. The biggest issue will be the expanded project management load.

Assessment – Flare is an extraordinarily powerful single sourcing tool. (See the six-part series on my blog at hyperword.blogspot.com for an overview of the single sourcing features.) These new micro content capabilities simply increase Flare’s single sourcing power. I don’t know any company that has made full use of all these features but between the existing features and the new ones for micro content, I can’t think of anything that I could not do.

There’s one more change to the micro content – creating context-sensitive Help at the field, or “object”, level. In the RTF-based help days, this was handled by “What’s This Help”. Over time, however, due to the effort that this called for on the parts of the help authors and the application programmers, field-level help largely disappeared. The enhanced micro content feature now supports field-level help by letting authors assign context-sensitive help IDs to micro content phrases. And rather than having to create separate topics for the field help, we can simply use text from a larger topic as the field help.

Assessment – I’m not sure how widely this capability of the micro content feature will be used because of the fall-off in the use of field help over the last 10+ years. But any company that wants or needs to create field-level help will welcome this feature.

Find and Replace Enhancements

Flare’s Find and Replace feature has always been very powerful. This enhancement boosts that power. The Find and Replace in Files tab is now split into two tabs – Find Text and Find Elements. The Find Text tab is largely the same as the Find and Replace in Files tab, letting you search for and replace text or search for and replace code in topics. But the new Find Elements tab enhances that by letting you search for types of items with conditions. For example, you can search for a category of item, including tag, class, style ID, inline formatting, or attribute. You can then specify what to search for within a category, such as a specific tag or class or a specific piece of inline format coding. You can then specify the replacement string. For example, from the examples in MadCap’s online help, you might remove a tip in all the topics. Or you might remove a Center class from all paragraphs in all snippets. Or you might remove local formatting from all topics in one folder. And so on.

Assessment – If you have to modify a project at the code level, or if you’re cleaning up the code from an old Flare project or a project from another authoring tool after import into Flare, the sheer power in this feature will put it at the top of your toolbox. My only reservation is that this feature is so powerful that you’ll have to carefully think through what you’re trying to do, and back up the project, before actually doing the work. (Both tabs have a Create Backup option which makes that easy.) I’d also recommend experimenting with it before actually using it.

Code Snippets

If you had to insert code snippets in your topics in the past, you probably did so in one of two ways. You might have taken a screen shot of the code and pasted it into the topic. This works but it’s impossible for readers to grab the code out of the topic to re-use it. Or you copied the code from another file, pasted it into the topic, and formatted it to make it stand out from the text. The new code snippets feature is like option 2 but better; it treats the code as an “object” that can be formatted in various language formats, and formatted for appearance, and adds a clickable “Copy” command that eliminates the need to select and copy the text like readers do now. Code snippets look attractive in printed outputs as well.

Assessment – This is a special-purpose feature, but it will come in very handy if you need to insert code snippets with syntax highlighting in your topics, such as in API documentation.

Collapsing and Expanding Tags in the XML Editor

If you create long topics with a complex heading structure, it can be difficult to keep track of where you are within that heading structure. Even with the structure bars turned on, different heading levels can start to look alike. Is that a Heading 2 or a Heading 3? The ability to collapse and expand sections in the XML Editor may make things easier. Simply click on the angled arrowhead to the left of the material – a heading, paragraph, etc. – to collapse that material. Clicking on the angled arrowhead again re-expands the material. Moving or deleting a collapsed head moves or deletes all the material collapsed under it. You can hide or show the collapse/expand indicators, just as you can hide or show the structure bars, by clicking the appropriate button on the lower toolbar of the XML Editor.

Assessment – This is a useful convenience feature.

New Plugin for ServiceNow

Flare added support for publishing to Salesforce and Zendesk in previous releases, a real benefit if you use Flare but have to create content to be published to those other systems. Flare 2020 adds support for publishing content to a third platform with the MadCap Connect for ServiceNow plugin. 

Assessment -- This is a very useful feature for ServiceNow users (as were the plug-ins for Salesforce and Zendesk) because they keep you within Flare’s single-sourcing feature set.

Summary

All the new features and enhancements are useful and continue MadCap’s tradition of pioneering. The enhanced micro content feature is the most impressive new feature in Flare 2020, but it also takes you further away from the “wing it” philosophy of development. A feature this powerful and wide-ranging needs careful planning and management to be used effectively. If you work in code, the enhanced Find and Replace feature is an unbeatable way to become more efficient – with the caveat that it’s so powerful that you’ll want to understand both the feature and what you’re trying to do very carefully before actually using it. And if you find yourself doing API documentation, or if you need to showcase code snippets in online and print output, you’ll appreciate the new code snippet editor.
Overall, Flare 2020 looks like a solid new release.

Monday, April 27, 2020

Contextualizing Our Content – One Step Beyond


On April 2, I gave a webinar for MadCap called “Contextualizing Our Content – Today and Tomorrow.” In that webinar, I briefly reviewed how traditional context-sensitive help (CSH) and responsive design work before discussing and demo-ing advanced contextualization. That involved customizing a Flare target in real-time, without regenerating the output, in response to simulated sensor data, such as a change in temperature reported by a temperature sensor. The idea was to show how content can be customized based on input from anywhere, not just from within the computer as in CSH and responsive design. The bigger idea was to illustrate an example of contextualization in support of the Information 4.0 concept.

I won’t describe that first webinar in any more detail. You can find it in the list of recorded webinars at https://www.madcapsoftware.com/resources/recorded-webinars.aspx#flare.

Several viewers asked what other criteria could be used to customize the content. Those questions lead me to do some further testing to see what other properties of the output could be modified without the need to regenerate the output – customizing the output in real-time by modifying a control file, saving the modification, and then simply refreshing the output. I didn’t test every possibility – this was a proof-of-concept test – but here’s what I found.

The input control data comes first. This could be external sensor data, as in the webinar, but, in theory, could be any kind of data from anywhere. One viewer asked if artificial intelligence data might work. I wasn’t able to test this but it should work. (If you’re the person who asked that question, please contact me if you’d like to discuss this further.)

The processing script comes next. I simulated this in the webinar by modifying the CSS file by hand but it should be possible to write a Javascript that captured the input control data and use it to create a new version of the control file (show.css in the webinar) or simply modify the control file.

The next issue, and the topic of this post, is what you can modify in the output. As the webinar showed, I could modify the content based on its conditionality. Because conditions can apply to almost anything in a Flare project, almost anything should be modifiable as long as the things to be modified are specified in a control file that’s in the Output folder. For example, I was able to modify the skin banner for tablets by changing the background-color under nav.title-bar in tablet.css in output > owner > HTML5 > skins > fluid > stylesheets. Similarly, I was able to modify the skin banner for mobile by making the same change but in mobile.css.

Here’s an example, first with the skin banner colors generated in the target output.

Desktop-sized:


Tablet-sized:


And finally, mobile-sized – i.e. phone-sized:


Now, here’s the same output but with the tablet and mobile banner colors set in tablet.css and mobile.css as described above. (I’m leaving the desktop-sized banner in red.)

Tablet-sized (the hex value for the silver is C0C0C0):



And mobile-sized (the hex value for the orange is ffa500):


It may be possible to control other elements of an output – as I noted above, this was more of a proof- of-concept than a complete test. But it does work. And as I noted in the webinar, this offers the ability to customize our outputs in response to a wide variety of environmental data. And it does so in real-time, which may open up industrial applications for which the traditional build process was too time-consuming.

It’s also just cool…

If you’d like to discuss this further, feel free to email me at nperlin@nperlin.digitalspacemail8.net.

Wednesday, December 11, 2019

Single Sourcing with MadCap Flare – Part 6 – Management


This post ends my series on single-sourcing features in Flare. It will be short and to the point…

The hardest part of using features like conditionality, placeholder, project import, and the like is keeping them under control. What happens when you don’t? Consider…

In the winter of 2017, I was hired by a company in Wisconsin whose project had about 20 conditions with about 1500 insertions. Unfortunately, the author who set up the conditions never documented how to use them. When she left, her replacements had no guidance for using the conditions so they guessed, with predictable results. The company could not be sure what they’d get from a build. I was hired to try to fix this situation.

I spent three days analyzing the project to figure out how the conditions were supposed to be used. At the end, I had to tell the company that I had no idea what the original author had done. My suggestion was to remove all the conditions, create a new set, DOCUMENT THEM, and then re-insert them. Not surprisingly, the company wasn’t pleased.

The only way to keep a project under control and future-proofed is to set formal standards for using single-sourcing (and other) features and document those standards and the project in general. As projects get larger and more complex, and as MadCap keeps adding useful new features, there’s no other alternative.

Good luck.

Wednesday, November 27, 2019

Single Sourcing with MadCap Flare – Part 5 – Other Features


My previous posts discussed the conditionality, placeholder, and project import features that provide so much single-sourcing power. In this post, I’ll discuss several lesser-known ones and one new one.

Conditionalized Styles

Most projects use one stylesheet but there are options. For example, you can create two stylesheets for use in a project and specify that stylesheet A should be used for online targets and B for print. The more efficient approach is to create one stylesheet and allow for stylistic variations in the targets by using the medium feature. Still another approach is to create one stylesheet and use the mc-conditions property in the Stylesheet Editor to literally turn a particular style on or off depending on the target.

You can find the mc-conditions property in the Unclassified property group if you’re looking at the styles by group, or alphabetically if you switch to the alphabetic listing.

CSS Variables

There may be cases where you want to apply the same property value to multiple styles. Consider color; you’d specify the same color for h1, h2, and h3. However, having to repeatedly specify the color makes it easy to make a mistake – typing the wrong digit in a hex-value color specification, for example. One solution is to specify the color in the body style, which propagates it down to the subsidiary styles, but this might still be a problem if you had to specify alternative colors for h4, h5, and h6. The CSS variables feature eliminates this problem by letting you specify the color in one variable and use that variable in different styles.

There are several steps involved in working with CSS variables – none complicated but detailed enough that I’ll recommend that you look at the CSS Variables topic in the Flare help.

Clean XHTML Target

We typically use Flare’s topic editor to create content for Flare targets but it also lets us create content – HTML files – for use outside Flare, in a wiki for example. However, external programs may trip over the MadCap-proprietary features. To deal with this, MadCap added the Clean XHTML target. Selecting this target generates the output using standard XHTML but strips out the MadCap-specific features. It’s not a widely-used feature, at least in my experience, but it does let authors add support for other programs without having to bring another tool into the picture.

Easy-Sync

It’s common for authors to have to import Word or FrameMaker files into Flare, converting them into topics in the process. The import can be a one-time task, after which edits are done by the Flare author in Flare. Alternatively, we may want the original author, who probably does not have Flare, to be able to continue to update the imported files in the original tool and have those change automatically flow into the Flare topics. The latter option is the basis for the Easy-Sync feature.

This feature is driven by two options on the Word or FrameMaker Import editor. Prior to version 2019 r2, we used the “Link generated files to source files” option on the first tab and the “Auto-reimport before generate output” option on the Options tab. (In Flare 2019 r2, these two options are combined in the Reimport group at the bottom of the Advanced Options tab.)

The Link option creates a link from the Flare project to the original Word or FrameMaker files. The Auto-reimport option tells Flare to compare the content from the previous import with the content in the files now. If they differ, Flare automatically reimport the Word or FrameMaker files, creating new topics and overwriting the topics from the previous import.

Easy-Sync lets us create nearly-automated publishing workflows. We create and maintain the content in Word or FrameMaker and use Flare as the publishing engine. The problem is that this feature overwrites the topics created by the previous import. For example, if we import a Word or FrameMaker file into Flare, breaking it up into topics in the process, and then add Flare features like links, those Flare features will be lost. So Easy-Sync is useful but it calls for careful project planning and management.

Responsiveness

One change affecting tech comm is the need to generate output to run on different devices – generally desktops, tablets, and phones. The output’s look may have to differ between the devices, and MadCap has been adding support for this with Flare’s responsive output and responsive layout features. (I gave a two-hour workshop on these features at MadWorld 2018.) Flare 2019 r2 adds a new feature in support of responsiveness, responsive conditions.

The responsive conditions feature adds responsiveness to conditions (sorry…). In prior versions of Flare, conditions were simply set to be included or excluded. The new responsiveness feature lets us specify that material be included or excluded depending on the output device. For example, we might use one graphic for a target aimed at desktop monitors but one with larger text for target aimed at phones. Or, my favorite example, automatically change the wording in a command from “Click the button” to “Tap the button” when generating output for a tablet or phone.

There are several steps to working with the responsive conditions feature, again none complicated but detailed enough that I’ll recommend that you look at the Responsive Conditions – Set By Media Query link in the What’s New section of the Flare 2019r2 help.

Summary

I hope these posts have given a sense of the range and power of the features that Flare offers for single-sourcing. Technically, they work well – the older features almost flawlessly after having gone through their birth pangs. The common problem with the features is managing them. That will be the subject of the last post in this series.



Monday, September 23, 2019

Single Sourcing with MadCap Flare – Part 4 – Flare Project Import


In previous posts, I noted that conditionality and placeholders are the foundations of single-sourcing but described them being used in single projects. What if you need to use the same elements in multiple projects? For example, if you want all projects from different authors to use the same product_name variable?

You can create those elements from scratch in each project but that’s inefficient. Or you can copy the control files for these elements from a main project and paste them into the child projects, but what happens if the author of the main project adds a condition? The main project’s modified control files must be recopied into each child project; it’s easy to forget or to copy the modified control file into the wrong folder in the child project. And it’s easy for a child project author to change the control file so that it deviates from the one in the main project, with a loss of consistency. There’s a better way, the Flare Project Import feature.

Conceptually, this feature is simple and much like copying the control files from the main project to the child projects. The difference is that when you copy a file from the main, or master project, to the child, the Flare Project Import feature maintains a link between the master project and the child projects and redownloads the file from the master to the child if a copied file has changed in either the master or child project. Consider the example below.


You decide that all projects must use the same CSS and Copyrights topic. So, you create a master project, the top box in the flowchart, and store the CSS and Copyrights topic there. (You could use any project as the master. However, that project may contain files that don’t apply in this scenario and are just clutter. It’s usually less messy to create a new project whose only purpose is to serve as the master.)

The authors of the three child projects then link to the master and download the CSS and the Copyrights topic to their projects. All other files in the child projects are different, but the CSS and Copyrights topic are identical.

Now, the author of one of the child projects makes a change in the copy of the CSS downloaded to that child project. Or perhaps the author of the master changes the CSS. As long as there’s a difference in the CSS, or the Copyrights topic, or any other shared file between the master and child project, Flare will redownload the version of that file from the master project to the child project and overwrite the version on the child project when the author of the child project generates the output.

The beauty of this feature is that it ensures consistency across the projects in which it’s used. You no longer have to worry about the authors of the child projects changing the color of the h1 style in the CSS or changing the wording in the Copyrights topic; the next time they generate their output, their changes will be overwritten by the official version of the file in the master project.

Better still, this applies to any file in a Flare project. You get invisible consistency across multiple projects. I consider this one of Flare’s coolest features and yet one of its least well-known because, unless you took a class or called in a consultant, you’d never know that the feature even existed. And the name, Flare Project Import, doesn’t really say what the feature does.

A few tips if you want to use the Flare Project Import feature:
       Create a separate master project and name it “Master Project” to avoid confusion. You can use any project as the master project, but this has two problems. First, using a real project as the master means that there will be a lot of files that have no use in the master/child model and are just clutter and potentially confusing.
       Document the feature to avoid creating “zombie” projects. The term comes from an old client who asked me to investigate why the CSSs in his group’s Flare projects kept reverting to some standard format even though the authors were deliberately modifying their CSSs. As the client said, it was as if the CSSs had become zombies. The problem was that a year earlier, an author had set up the Flare Project Import feature but didn’t document it, then left the company. So the feature was working perfectly but no one knew why or what to do about it. Avoid this problem, and spare yourself the need to call in a consultant, by documenting the project.

That’s it for Flare Project Import. Next up – conditionalized styles and CSS variables.


Monday, September 9, 2019

Single Sourcing with MadCap Flare – Part 3 - Placeholders


Another Flare feature that supports single-sourcing is placeholders, which Flare offers in two forms – variables and snippets. Placeholders let you insert the same content in multiple places in a project, such as multiple topics, and automatically change that content everywhere with just a few mouse clicks.

For example (from the introductory post), let’s say that you’re documenting a new product whose pre-release code name is Longhorn. You write the word “Longhorn” in hundreds of places throughout the documentation.

Then, just before release, Marketing changes the product’s name to Vista. You now have to search the documentation for all instances of “Longhorn” and change them to “Vista”. It’s easy – just do a search and replace.

But what if you misspelled “Longhorn” several times? A search and replace won’t fix that. You could do a fragmentary search and replace – search for “Long” – but that would give many false hits. 

Or, let’s say that you have to repeat the same set of steps in multiple topics. Easy – type the steps once, then copy them and insert them in the appropriate topics. But what happens when one of the steps changes? You have to find each insertion and change it. But how do you know where you inserted the material. You might keep track of the insertions but that calls for an unusual level of management. You could again search for the insertions but that might again bring up false hits. Placeholders are a solution in both cases.

Variables

The simplest placeholder is the text-only variable. In the first example, rather than typing the product’s name over and over again, you’d create a variable called, perhaps, productname, and set its definition (its value) as “Longhorn”. You’d then tell Flare to insert the value of the productname variable wherever you wanted the word “Longhorn” to appear in a topic or other file.

Then, when Marketing changes the product name, you’d simply change the value of productname from “Longhorn” to “Vista”. Flare then automatically changes the “wording” everywhere you inserted the variable. You don’t have to keep track of the insertions – Flare does that.

Variables are easy to create and use. What can be tricky is defining them. For example, what do you do if you need to use a variable as a possessive – if you want to say “Longorn’s features include…” Do you create two variables called productname and productname_possessive with values of Longhorn and Longhorn’s, or do you use the single productname variable and type “’s features include…” and insert the productname variable in front of the “’s”? Either approach works; you just have to define which approach to use and get all authors to agree.

Flare stores variables in a file called a VariableSet, with an extension of flvar, accessible from the Project Organizer pane. You can create multiple VariableSet files if you want to categorize multiple variables or simply break multiple variables into smaller groups.

Several points regarding variables:

  • Variables usually have one value but you may need more sometimes for different outputs. For example, you might be generating US and Canadian outputs and have a variable called country. You specify that the value of that variable is US. But if you’re generating Canadian output, you’d want to change the value to Canada. You can override the US value on the Variables tab of the Target Editor but it’s a good idea to minimize the typing needed to specify output settings. The solution is to create the country variable, specify its value as US, but then click the third icon, Add Variable Definition, on the VariableSet Editor toolbar. You’ll see a second instance of the country variable, greyed out, and can now type the additional value, here Canada.
  • How then do you tell Flare what value to use for a particular output target? On the Variables tab of the Target Editor, there’s a dropdown link to the right of any variable that has multiple values. Click that dropdown link and select the desired value.
  • In addition to the standard variables, you can also specify date and time variables. One common use is to add a variable that specifies when the output was generated and that’s automatically updated. Click the second icon, Add DateTime Variable, type the name, such as Generated On, then click in the Definition field. When the Edit Format dialog box opens, type the format – click the I icon for help – then specify when to update the variable.

Snippets

Snippets are similar to variables but more powerful because they can contain anything you’d enter in a topic – text, lists, images, tables, links, formatting, and so on – including variables. In example two above, rather than typing the steps, copying them, and pasting them into the appropriate topics, you’d create a snippet called, for example, task1_steps. You’d then insert the task1_steps into the appropriate topics. When the time came to change one of the steps, you’d change it in the snippet itself. Flare would then automatically change the “wording” everywhere that you inserted the snippet. Again, you don’t have to keep track of the insertions – Flare does.

Each snippet exists in a separate flsnp file that’s accessible from the Resources folder on the Content Explorer. (You can put the snippet files anywhere you want within the project’s structure. I just find it simplest to store them in the Resources folder.)

Several points regarding snippets:

  • You can create text snippets and block snippets. A text snippet consists of one paragraph of text or less. If you insert a text snippet on a new line or in an existing paragraph, it keeps its structure as a line of text. A block snippet consists of two or more paragraphs of text or other element followed by a return, such as a graphic. If you insert a block snippet on a new line, the snippet retains its paragraph structure. However, if you insert a block snippet in an existing paragraph, the block snippet paragraphs become run together.
  • As noted above, a snippet can contain a variable. However, because you can assign conditions to snippets and variables, it’s possible to have a snippet to which you’ve assigned a condition to be excluded for a particular output but that contains a variable to which you’ve assigned a condition to be included for that same output. In such a conflict, Flare will default to an include so it will display the snippet because it contains the variable. The problem here is a management one; you’ll be wondering why that snippet displayed in the output when you thought you’d excluded it. Keep careful track of how your snippets, variables, and conditions interact.
  • If you have numerous snippets and need to modify one, it can be hard to pick out the right one. The shortcut is to find one instance of the snippet, right-click on it, and select Open Link. This immediately opens the correct snippet file, saving you the trouble of hunting for it.
  • Snippets can solve one limitation of variables. What if you want to end a step in a procedure by telling the users to “Press Enter.” You might create a variable called actionstep, for example, whose value is “Press Enter”. But what if you want the action step’s value to be “Press the Enter icon” followed by the actual Enter key icon. A variable is text, so that won’t work. However, you could create a snippet called actionstep that contains both the text and the icon.


As with conditions, common problems with placeholders are in design and management. We often give placeholders names that are not clear. The result? Other authors using the same set of variables or snippets won’t find what they’re looking for and wind up creating duplicates, which complicates project management. A related problem lies in not documenting the rules and logic to use if an author really does need to create a new variable or snippet. As with conditions, when you leave and a new author comes on the project, they may send the project off the rails because the lack of documentation makes it easy to make mistakes.

That’s it for placeholders. Next up – Flare Project Import, one of Flare’s coolest and least-known features.



Tuesday, August 27, 2019

Single Sourcing with MadCap Flare – Part 2 - Conditions


In post 1, I said that you can create one source of content and use it for multiple outputs, or select a sub-set of the content for each output. This is one of the foundation concepts of single-sourcing.

Let’s say that you create a sales procedure manual for use in the US and Canada. Some of the material applies only to the US, some applies only to Canada, and some applies to both. You could generate one manual that contains all the material and tell US users to ignore material that applies only to Canada and vice versa. A better solution is to extract the common material and the US material to create the US manual, and the common material and the Canadian material to create the separate Canadian manual.

This capability is driven by conditionality, one of the core features of single-sourcing.

Conditionality

To repeat my initial description from the first post, conditions are essentially categories. To repeat the US/Canada example above – let’s say you have to create a sales procedure manual for use in the US and Canada. Some of the material applies only to the US, some applies only to Canada, and some applies to both.

Conditionality lets you define categories of “US only” and “Canada only”. (Material common to both, or all, categories is always used so it’s not conditionalized.) When you generate the US output, you’d tell Flare to exclude any content categorized as “Canada only”. The output would contain the common material plus the US material but not the Canadian material.

You can apply multiple conditions to material. For example, say that the sales procedure manuals will not only include material specific to the US and the Canada but also slightly different material in the online and print versions. So, to create the online sales manual for the US, after applying appropriate conditions to the appropriate material, you’d tell Flare to exclude any material categorized as “Canada only” and any material categorized as “print only”. The resulting output would contain the common material plus the US material and online material but not the Canadian or print material.

In addition to controlling the behavior of topics, conditions can have wider effects. For example, say that you create a general table of contents that lists topics A, B, and C. The actual topic C is conditionalized as “Canada only”. When you tell Flare to exclude “Canada only” material when generating the US output, it excludes the topic and automatically removes it from the table of contents as well. And if topic A has a hyperlink that points to topic C, Flare automatically turns that hyperlink into regular text in order to avoid a broken link.

Conditions are very flexible. You can apply one or more of them to a topic or multiple topics and to any content within a topic, as finely as a single character. You can also apply them to any other project element – images, master pages, stylesheets, and even to other conditions. (Although I’d have serious reservations about doing that in real project.) This flexibility makes them very powerful but also requires that they be used and managed carefully.

The two problems that I most often see with conditions aren’t technical but rather ones of management and design.

  • The first problem lies in not documenting the logic behind the conditions clearly or at all. When the initial author leaves and a new author comes on the project, they may send the project off the rails because the lack of documentation makes it easy to make mistakes when applying or invoking conditions.
  • The second problem is the rapid growth of permutations as you add conditions to a project. With one condition, for example, there are only two permutations – include or exclude. With two conditions, however, there are four permutations – include/include, include/exclude, exclude/include, and exclude/exclude. With three conditions, eight permutations. And so on. It’s easy to get confused when to include or exclude multiple conditions in combination. And it’s easy to get confused as to when to apply them at all. The solution ties back to that for the first problem – document the logic behind when to apply conditions in a project and when to include or exclude different conditions in what combinations.

When might you use conditions in a project?

  • Some uses are obvious – If you have to categorize material in a project as applying to the US or Canada, for example. A similar example would be to categorize material as applying to system administrators, professional users, or clerical users. When generating output for clerical users, you’d then exclude material conditionalized as “system administrator only” and “professional users only”.
  • Another use is to document a project for new authors to reference or current authors to get up to speed after being off the project for a while. You can document a project in a separate Word document, for example, but that might get lost. A better approach is to document the project in topics that are part of the project and with authors notes inserted in specific topics. But you don’t want users to see this material, so you create an “author’s notes” condition, apply it to the topics and the in-topic notes, and then exclude that material when generating the output.
  • Another use is to control which topics are made available to the reviewers. You could include all the material in the output and add instructions telling the reviewers to ignore topic 10 because it’s not finished. The problem is that some reviewers may not read the instructions, review topic 10, and give you scathing feedback about how topic 10 isn’t finished. You can avoid this by creating a condition called “not ready for review”, applying it to topic 10, and excluding the “not ready for review” condition on output.

That’s it for conditions. Next up – placeholders (aka variables and snippets).