Flare Help Content Strategy

[Mark A Johnson]

This isn't a question about Flare itself, but about the Flare Help content. I think it is really well organized and helpful. Is there a name/convention for the content strategy that it uses?

My team is working on a new content strategy for all our help projects (including many different products). Right now most of our help is organized according to the menus in the UI. The menus and dialogs are described along with steps that explain how to use them. I have found this organization very limiting when trying to create higher-level procedures/tutorials that guide users through learning the product. Since procedures generally touch various parts of the UI, I have found that separating the description of the UI into a totally separate area and referencing that from procedures/tutorials is extremely efficient and also conducive to single sourcing. (This is how other projects I have worked with are organized, and now I see that Flare is set up this way as well.)

I am getting fierce resistance to this concept from a senior writer on my team who wants to keep the organization of our product UI the same as his TOC. He says this helps users find the content they need. My argument is that customers need to be shown how to approach using the UI from a task/objective-based approach that is completely detached from the way the UI is organized. And, putting the UI descriptions in a separate place (e.g. the "Interface" menu in Flare) allows writers the flexibility to do this.

I have been doing this a long time and I have worked with a lot of help projects. Right now the stakes are very high, as the team will be stuck with whatever content strategy we choose for years. The writer opposing the idea of separating out descriptive UI content outranks me, and is most senior on the team other than the manager. Even though I have converted portions of his project to demonstrate my strategy, he claims he does not see the merit. (He has a very large project and it would take a lot of work to convert it.)

Thanks for reading. Any insights about the Flare content strategy or advice related to content strategies in general greatly appreciated.

Mark

[NorthEast]

I'd agree with your approach.

I prefer to organise content based on the tasks that your reader wants to perform. (Which may or may not be closely aligned with the UI.)

If you organise content based on your UI, you're assuming that your reader intimately understands your UI, otherwise they won't know where to look.
(And since they've had to look at your help, they probably don't.)

Perhaps show the two versions of your help to real customers (or anyone unfamiliar with your product), and get some feedback. You can each have your own personal opinions, but it's easier to make your case if you can back it up with research and evidence on what your customers actually prefer.

[Nita Beck]

I generally agree with your approach as well. There is no one-size-fits-all way of organizing one's content or one's TOC/navigation, so I can't offer a hard and fast rule. For one of my clients who has upwards of 40 Flare projects, content is organized is a sort-of-DITA-ish way, so we have folders for concepts, tasks, reference, faqs, tutorials, and any other category that makes sense. Keeping a uniform structure like this makes it easy for a writer who generally works in one project to be able to find their way in any other writer's project.

Regarding the TOC/navigation, the TOC for at least one of the projects very generally follows the UI in the sense that the UI's ribbon (the application is a desktop Windows application that controls manufacturing inspection equipment) generally follows the recommended workflow, with the first tasks a user would do accessible from the first ribbon group, the second tasks are in the second ribbon group, and onward along the line, with the stuff at the far right of the ribbon being the miscellaneous things.

[chuck_agari]

MadCap's content strategy is "more is better." And "hide stuff behind eye candy that you have to take extra steps to view."

When I see documentation that explains what all the menu items and buttons do and is organized in that fashion, I assume it was written by an engineer, not anyone trained in basic technical communication concepts. (Although I should not that while I also firmly believe that technical communication is properly an engineering discipline, I also know that the connotation here will be understood.)

[Scotty]

Devil's advocate....

The senior guy's approach has the very strong advantage in that it is easy to maintain, and easy to see 'where you're at' at any point in time. For example, a change in one part of the UI requires only a change on a single topic, but your approach will likely require changes in multiple places, which is hard to track and takes more time to update (multiple content changes, multiple points of review).

Also, his / the manager's priority may be shipping something that meets your company's contractual obligations, and not much more, for a variety of potential reasons (workload, time spent better elsewhere, politics, etc).

If the product is large and complex, with lots of configurations and modules and so forth, something approximating his approach is fine. Add a cache of task-based topics separately, whether in the same user help or in a blog or separate tutorials.

Of course, a well-designed and implemented product UI and user experience should largely negate the need for the content in his approach, but that's a whole different kettle of fish.

[Mark A Johnson]

Devil's advocate....

The senior guy's approach has the very strong advantage in that it is easy to maintain, and easy to see 'where you're at' at any point in time. For example, a change in one part of the UI requires only a change on a single topic, but your approach will likely require changes in multiple places, which is hard to track and takes more time to update (multiple content changes, multiple points of review).

It's true my approach will potentially require the writer to make multiple changes to address a single UI change, but I think that extra work is necessary especially when the same UI change is needed in multiple workflows/procedures, particularly in large, feature-rich products with many modules (including this one).

Say you have a minor setting in a preferences dialog that is referenced in three important but unrelated procedures. You wouldn't put all three procedures in the preferences dialog topic simply because they share this setting. If your help content organization is based on your product UI, you choose the UI element primarily relied upon for the procedure and put it there instead. Then, you add a link to the preferences dialog from within the procedure.

Now, say each of these procedures depends heavily upon settings from two dialogs other than the preferences dialog, in fact, let's say it isn't clear which dialog is primary. The writer is forced to choose one of the two dialogs to bind the procedure to. How can this be addressed? Perhaps one is chosen at random and links are added to the other, or a snippet is added to both. This quickly becomes unsustainable if the procedure is dependent upon many such dialogs and UI elements. What is the (common, objectionable) solution: The writer simply doesn't write procedures that require multiple/diverse UI elements, and instead limits procedures to those confined to a specific area of the UI. This assumes (as you mentioned) the engineers/designers have already crafted the UI in a way that is intuitive for users - the exact case that makes help documentation unnecessary. It gets through because gaps in continuity that are obvious hindrances to users are overlooked by reviewers familiar with the product who are instead looking for technical accuracy and completeness. The writer wins because the content is complete, accurate, and easily maintained. The user is marooned, unable to connect the dots without an arduous research and discovery process (made possible through searching).

Any mid- to high-level procedure in a sizable product employs a variety of UI elements to achieve its objective, and the most salient content required by users is the content that resolves the combinations of UI employment that are not intuitive. My content strategy prioritizes this high-value content and is also easily maintained...here's what I do:

To convert a UI-dependent help project to the content strategy I am proposing, I simply identify the essential objectives required of the user (starting with the basic), and then do the same research and discovery efforts the user would otherwise be required to do in order to be successful. I then put the procedure for each objective in order according to a plausible method the user could follow in order to be successful, with links to every dependent procedure/objective when needed. (This process tends to instantly spider into deep corners of the UI.) I pull out all the descriptions of the UI and put that content into an entirely separate 'reference' section, and reference it when I need to (these topics are also used for the help buttons). How do I keep this sustainable? Each procedure that uses a UI element is linked to from the UI element's topic - providing a reference while updating. This also allows users who accessed the topic from a help button see the related procedures.

A criticism I have had with this approach is that there are too many links. This seems absurd to me after arduously searching and reading massive amounts of content just to do exactly what is expected of the user. I need to use links every time there is ambiguity about what the user needs to do next. There are exactly as many as needed, and then a few more to add convenience, but users will need to use them way less than the seemingly arbitrary way they are used in UI-centric help.

The second criticism is that the descriptive content is duplicated by the procedural content. But it isn't duplicated. The procedural content employs the parameter/option/text in the context of some specific higher user objective. The descriptive content of the UI is in the context of the technical properties/functions/limitations of the parameter/option/text field being described. There is no overlap, even though the user will often be able to make inferences of one from the other.

To sum up, I think the application of higher-level procedures and continuity with necessary links is essential to user success (in addition to comprehensive UI descriptions), and a content strategy something like the one I am proposing is a way to make this sustainable. (Of course, if meeting contractual/minimal obligations is the objective - and they do not require what I am suggesting - by all means do that!)

This got long winded. I really appreciate the feedback here. I think having a chance to bounce these ideas around a larger community of writers is hugely beneficial and I look forward to any additional comments you have, especially those that challenge/trash my theories and/or sanity.

[NorthEast]

If you make the content more task-based (rather than UI-based), then yes it will probably require a bit more thought and effort about structuring the content, and it may cause some duplication.
So I understand the criticisms, but it sounds like they're complaining that it makes things harder for you as writers, rather than focussing on what's good for your users.
But what's the most important thing here - is it what's easiest for for you the writers, or is it producing better content for your users?

The usefulness of UI-based content is going to be directly related to the quality of your UI.
- If you have a great UI that's easy to navigate, then your content should be easy to navigate too. (Good UIs are going to focussed on the tasks the user wants to do, not on what the dev team thinks is logical.)
- But if you have a complex or bad UI that users find difficult to navigate, then users will have difficulty navigating your content too. Blindly following the pattern of a difficult UI just means you're failing twice.

You shouldn't force the user to learn your product UI in order to find things in your content. Your content needs to be focussed on what your user wants to do, whether or not that's closely aligned to your UI.

[ChoccieMuffin]

@Mark, you have explained very clearly the difference between a REFERENCE guide and a USER guide. In general, a Reference Guide is easier to write, and can be very helpful for the user, but a User Guide, which really should be task-based, is clearly going to be more difficult to produce, particularly for a complex product.

I will be following your journey closely, as we have some very complex products and the chance of a serious bit of rework some time soon.

[Mark A Johnson]

There is general agreement on the team that the user should be provided a task-based set of 'getting started' instructions. Since most of our products are currently (essentially) reference guides with granular steps compartmentalized within UI element topics, I fear such an effort would consist of simply creating general overviews in ordered lists of links to one UI element topic after another in the general order they would be used for the various objectives. Again, to someone very familiar to the product (especially to someone without support experience), this seems logical, even bulletproof, but the devil is in the details.

When the user is given what they believe to be the procedure they need, and are directed to a topic that is primarily a description of the UI, continuity is broken by descriptions of any UI elements/parameters in the topic that are not required for the current task. If the UI is organized so that each dialog/form is specific to a single task, and this is consistent across the product, of course ordering the dialog/form topics will work beautifully (although descriptions would hardly be necessary, just the procedure for how to use the dialog - but at this level it's probably obvious). In my experience, no UI is actually one-to-one like this unless the product is so well-designed and specific in its objectives that documentation is unnecessary.

In any product with even moderate complexity engineers/designers employ some dialogs/forms for a multitude of potential tasks. Why? Because the same chunk of code often works in several workflow contexts. Obviously, we're talking about objectives that can't be automated by the engineer, and beyond that the designer doesn't have the resources to accommodate every context - to do so would essentially be a redesign of the product into wizards (or something similar) for every potential objective. As a product owner, why not do this? Why not invest big $ to make the UI completely intuitive? Because it's way cheaper to hire a good technical writer and provide adequate documentation that resolves the ambiguities and provides the customer an approach for all the essential contexts and objectives supported by the product. And, if the doc is sufficient to accommodate the required tasks, the customer accepts it - they don't always need the UI to hold their hand and they don't want to pay for it either so long as they can get the job done. But, they need to be able to get the job done.

Videos have been proposed as a way to accommodate various workflow contexts. I am in support of short, high-value, thoughtfully constructed, and well-produced videos. I think they can both lead to user success and offer trial customers an incentive to purchase. However, I do not believe videos can replace the need for a procedure-based user guide for most products. Again, the devil is in the details. Sure, a suite of thousands of videos (with potentially references within) could accommodate every workflow context and objective for a moderately advanced product, but this is neither sustainable for the writers nor efficient for many users. Once a workflow has a few variables and dependencies, its viability as a video becomes limited without significant effort, and if many references are required a video is inappropriate. Users who are stressing the product and using advanced (often highly-valuable) features won't want videos anyway - they need the nitty-gritty details, and they hope a writer has put a well-referenced procedure together that accommodates them. As writers we are holding a lot of these highly-advanced users by a strand, and we need them to be successful so they will continue to use our product and not our competitor's product. In my opinion, the primary functions of the product should be delivered as videos, and the content of the videos should match the content of the primary procedures described in the user guide (or perhaps include an overview). So, basically they will be redundant with existing content - another reason they should be limited. I think the videos should be used for marketing content for potential customers and also be of functional use to new customers. For content beyond what is appropriate for a video (including most content that is applicable to most users), I believe highly-relevant, objective-based procedural help content using the content strategy I have described is necessary to achieve reliable customer success.

[clpha6]

I have been trying to implement an approach like this. I started adding mini menus of "next step" links throughout my help project. I had been hoping to use Flare's relationship tables for more automated connections, but got lost and gave up. I might try to tackle that again.

I wanted to structure this like a Choose Your Own Adventure book. You want to do this? Follow these steps. You want to do that? Follow those other steps.

[Mark A Johnson]

Right, I've actually used the term 'choose-your-own-adventure' in my proposals. Exploring a UI or reference documentation can be like an adventure in largely-uncharted territory. Yes, the terrain is marked, but there is no unambiguous signal directing you to the next required landmark based on your current condition and overall objective. As tech writers, by identifying these variables and responding to them in our content (with links), we can provide the most direct route without any ambiguity, breaks in continuity, or clutter for any objective the product supports. (Of course, unlike a real choose-your-own-adventure, the 'correct' choice should be clear.) At points users will need to take steps back because they haven't set up the necessary preconditions for what they want to do. (Ideally the help will return them to their original departure point when the preconditions are met.) At points they will be able to skip ahead or maybe do things they didn't realize they could do.

Unfortunately, the kind of content organization required to facilitate this isn't obvious. In my opinion, it requires a content strategy that segregates reference content from procedural content, and includes references/links at every point of ambiguity within the procedures to the next step required of the user based on their needs/condition.

I haven't used relationship tables, but it looks like those are links added automatically to topics based on a table. For what I'm proposing I think it is optimal to put links directly within steps (at each relevant 'choice' point).

[ChoccieMuffin]

Do be aware that it's not possible to have "see step 6" or "if you don't need to do that, skip to step 8" kind of thing in Flare, because the step numbers aren't something you can stick a x-ref to...

We try to do procedures etc, but when describing dialog boxes we often have to resort to
1. Open dialog box.
2. In fields A and B enter information.
3. Complete the dialog box fields as required
----2-column table, with headings Option and Description. Description column give explanation about why you might want to select a check box or not, with loads of x-refs to other parts of the docs to give more detail.

Not ideal, but the best we could come up with, given the limitations. Also, if someone presses F1 while using the software, it isn't possible to know WHAT the user is trying to do, just that they're in that particular dialog box, so a help topic like that (where fields A and B are fairly obvious but other options could be used for all sorts of things) at least gives them some kind of reason for why they should select or clear a check box.

I particularly hate help files that say "you can do X" or "you can do Y" but don't say HOW you can do X or Y!

[Mark A Johnson]

Also, if someone presses F1 while using the software, it isn't possible to know WHAT the user is trying to do, just that they're in that particular dialog box, so a help topic like that (where fields A and B are fairly obvious but other options could be used for all sorts of things) at least gives them some kind of reason for why they should select or clear a check box.

Right. It's impossible to know what the user's objective is when they click a help button. I think it is essential to accommodate the case 'I just need to know what this check box/setting/etc. does.' Therefore, I treat help buttons like a way to use the product's UI as essentially a visual index for the reference content. Users learn fast they can count on help buttons to open the topics that answer the question 'what does it do' for every interface item. I don't have any steps in the descriptive content - just a screenshot of the dialog (or whatever), then 'How to Get There' and 'What it Does.' How does the user find out how to do whatever they are doing? They link to one of the procedure in the topic. As I mentioned earlier, in every UI description (i.e. 'reference') topic, I include a list of all the procedures that employ an element of the dialog.

Do be aware that it's not possible to have "see step 6" or "if you don't need to do that, skip to step 8" kind of thing in Flare, because the step numbers aren't something you can stick a x-ref to...

All of my links to procedures open the topic .htm or a heading. If there is a digression within a set of steps, I'll break that off into a different procedure. (I've found that usually digressions are referenced by other procedures anyway.) I'll only refer back to a specific step within the same list.

We try to do procedures etc, but when describing dialog boxes we often have to resort to
1. Open dialog box.
2. In fields A and B enter information.
3. Complete the dialog box fields as required
----2-column table, with headings Option and Description. Description column give explanation about why you might want to select a check box or not, with loads of x-refs to other parts of the docs to give more detail.

I omit steps like this altogether except in a larger context. Within a procedure I'll say:

1. Choose menu > submenu to open the * dialog box.
2. Complete the required settings and click OK. See [* dialog box (link to reference topic)] for more details.

I've found there is no need to explain filling out forms and settings. I've also found omitting content like this can cut the size of many help projects in half while at the same time making the projects more effective (so long as the more comprehensive procedures exist).

[chuck_agari]

Do be aware that it's not possible to have "see step 6" or "if you don't need to do that, skip to step 8" kind of thing in Flare, because the step numbers aren't something you can stick a x-ref to...

Maybe Flare can't do that, but it's certainly something that can be done. It'd have to be done programmatically, of course, either when generated (as with a PDF) or on the fly (for online outputs).

[Nita Beck]

Do be aware that it's not possible to have "see step 6" or "if you don't need to do that, skip to step 8" kind of thing in Flare, because the step numbers aren't something you can stick a x-ref to...

Maybe Flare can't do that, but it's certainly something that can be done. It'd have to be done programmatically, of course, either when generated (as with a PDF) or on the fly (for online outputs).

(To the original poster, sorry for taking your post even further afield.)

Actually it can be done, in Flare. I covered this in one of my two sessions at MadWorld 2019 San Diego a few weeks back.

Here's the code for the example I showed:

Code: Select all

/* Example of using OLs but suppressing the list style and using Flare autonumbers instead so we can xref to list items */

ol.StepNum
{
}

ol.StepNum > li
{
	list-style-type: none;
	mc-auto-number-format: 'X:Step {n+}. ';
	mc-auto-number-position: outside-head;
	mc-auto-number-offset: 60px;
	mc-auto-number-class: StepNum;
}

ol.StepNum > li:first-child
{
	mc-auto-number-format: 'X:Step {n=1}. ';
}

span.StepNum
{
	color: red;
	font-weight: bold;
}

MadCap|xref.Step
{
	mc-format: '{paranumonly}';
}

Several things are going on here.

First, we have an OL whose class is StepNum. I didn't otherwise define anything special about it.

Second, we have a complex selector that says, for LIs within ol.StepNum, turn OFF its regular numbers by setting its list-style-type attribute to none. Then let's use a Flare auto-number to say that list items will be autonumbered with an incrementing number. We also do a few other things for formatting. Plus, notice that we're going to control the formatting of the auto-number by using a span, rather than using formatting widgets such as "{b}" as part of the format.

Third, we have another complex selector that says, oh, BTW, we want the FIRST list item within ol.StepNum to always reset to "1".

Fourth, with span.StepNum, we define how we want to format the auto-number. For illustration purposes, we'll make it red and bold.

Finally, we have an xref format so that we can have xrefs point to the list items within ol.StepNum.

The result will look something like this.

If it's any consolation to the community, I figured out how to do this only within the last several months.

[ChoccieMuffin]

Nita, as always you have described a very elegant solution, which I will read and inwardly digest because it's lovely (as are you) and it's very helpful (as, again, are you). My original comment missed out the all-important proviso that Flare can't do it OUT OF THE BOX the same way Word or FrameMaker can, but I'm kinda glad my post was incomplete, because otherwise you might not have posted your solution!

(I've had a really confusing day so it's a total treat finding such treasures in the Flare forums, no wonder I'm in here every day!)
Happy Thursday, everyone

[Nita Beck]

Thanks for the kind words.

About your post being "incomplete"... I readily admit that I readily SKIM forum posts, and sometimes I inadvertently post a response that clearly indicates that I've totally missed some important point.

[BaritoneJP]

Here's the code for the example I showed:

When I use the solution you explain in this post, the resulting output has the list in a table. Why is that?