Tasks in Topics vs Snippets for Help and PDF

[Carlsen]

Hi All,

I'm hoping someone can help me with some tips about how to structure my topics and snippets to help me get the results I want in my HTML5 Help and PDF output. Here's my situation:

- Our help uses drop-downs extensively, much like the Flare 9 help does. So for example in one topic we may have drop-downs for tasks: Add User, Update User, Delete User.
- I would like each of these distinct tasks to be their own Flare topic file so that I can easily single source the Add User topic with the Installation Guide, which is PDF output.

And here's the problem:
- If I want to have individual topic files for each task, I can't assemble them into the larger topic unless they are snippets because Flare does not allow you to insert a topic within another topic. (Which is strange to me since a topic's HTML is essentially the same as a snippet's HTML--only the file extension is different.)
- I could make each task a snippet and solve the above problem, but then I cannot single source the Add User topic with my Installation Guide PDF because you can't insert a snippet directly into a PDF's TOC (okay, you can insert it, but when you generate the PDF it throws an error).

The way I've handled this now is to not split up my tasks into topics, and conditionalize everything in the larger topic and insert the whole larger topic into my Installation Guide TOC. I don't like this, but I couldn't think of any other solution, which I'm hoping someone on this forum can help with.

So, does anyone know how to deal with this problem well? So that I can construct keep my tasks as individual topics, but still have a larger help topic with multiple tasks in it?


Thanks,
Josh

[Msquared]

- I could make each task a snippet and solve the above problem, but then I cannot single source the Add User topic with my Installation Guide PDF because you can't insert a snippet directly into a PDF's TOC (okay, you can insert it, but when you generate the PDF it throws an error).

Correct, but for your installation guide, you could create a *topic* called Add User (or whatever else may be more appropriate for your installation Guide) and put the Add User snippet in it. This isn't as much of a duplication as it sounds. On some occasions you may find that you need slightly different "wrapping" or "context setting" text when the snippet is placed in your Install Guide to what you need when the snippet is placed in your HTML help.

I'm still working out the best way to do this, and I'm coming down strongly in favour of single Flare topics with multiple concept, task and reference snippets, where necessary. When I first put my User Guide (PDF) into Flare, I used a Flare topic per content topic, so I had, About Users (concept), Adding a User (task), Deleting a User (task) etc.

My User Guide content is single-sourced with my WebHelp, so with this structure I get a nice level of granularity in my WebHelp TOC, but lots of very short topics. I use relationship tables to group related topics and display links at the bottom of each page. However, as happens often in my world, every time the developers add or change some functionality significantly, I end up having to add topics or rename existing ones to reflect changing user tasks (for example, Adding a User to a Group may become "Configuring User Security" - not a great example, but you get the idea, I hope). Then, there are lots of things to update, TOC, relationship table, alias files etc.

Now, for my newer content, I'm creating my Flare topics at a less granular level, for example Users. So in the WebHelp About Users, Adding a User, Deleting a User etc are all on dropdowns. With suitable online-only and print-only conditionals this works perfectly for the PDF too. I haven't yet snippetized any of this content, as I haven't yet ported the other document that could use some of it to Flare, but that's what I'll be doing one day, as required. And, I can cope with quite significant interface changes without needing to move and rename lots of files.

Incidentally, if you're interested in how to decompose your content into "topics", I found this article very interesting http://idratherbewriting.com/2014/01/05 ... -concepts/ It's not Flare-specific, in fact, it uses DITA examples, but it makes some very good points about what makes a single useful chunk of information, and it's validated my instinct to move towards the less granular approach. I wish I'd read it sooner!

[Lydia]

Hi Josh,
you say that you want to assemble the small topics into a bigger topic. Unless I misunderstood, you may be able to do that through the TOC.
The question is - is it necessary to 'physically' have the smaller topics inside the bigger topic? Does the bigger topic contain information or is it just a container?
Depending on the answers, you could use a book in your TOC.
- If the bigger topic contains text, link the book to the bigger topic. Put the smaller topics in the TOC hierarchy under the book.
- If the bigger topic is just a placeholder with a heading, give the book the heading name and make sure that you 'inject headings for unlinked books in TOC' (this is on the Advanced tab of the target'). Put the smaller topics in the TOC hierarchy under the book.

Regards, Lydia.

[Carlsen]

Hi Marjorie,

That's a great article. What it shows is exactly what I want to do. I want to combine my task topics with my concept topic to create one larger help topic. Unfortunately, this won't work on Flare's TOC because it will just make a folder for the concept topic and place the task topics within that folder. I really don't see any way to do this in Flare other than writing all of your tasks as snippets. Writing so much of your content as snippets seems wrong to me, and this seems like something Flare should be able to do.

While I agree with your solution for single sourcing snippets in PDFs by creating a topic to hold them, this also seems like an extra hoop you need to jump through that should be unnecessary.

There are some situations like this where Flare doesn't seem to single source as well as advertised. Unless someone else replies with a solution to this problem, I think I'll submit a feature request because I think more and more tech writers are moving in this direction and Flare should be able to handle the files in a sensible way.


Thanks,
Josh

[NorthEast]

You say it doesn't seem right to use snippets, but isn't the method of using snippets roughly similar to how the content is combined in that DITA article?
For example, in the DITA article 'topics' (source) are combined into 'articles' (output), which seems equivalent to combining 'snippets' (source) into 'topics' (output) with Flare.

I don't see how a topic could reasonably be inserted inside another; for example, how do you have a link to a topic if there's only one instance of the topic, but it's re-used in five different locations (container topics)? When using a snippet, you're forced to create each topic/instance where the snippet is used.

[Msquared]

Writing so much of your content as snippets seems wrong to me, and this seems like something Flare should be able to do.

I think it depends how you see snippets, and perhaps the name doesn't help here. The name "snippet" does imply something quite small. How about if you start referring to them as "chunks"? Then you can have small chunks (for example, a standard warning notice) and bigger chunks (for example, a whole task that is a procedure with 15 steps that describes how to install a particular piece of software). Let's call the latter chunk-topics for now.

However, I'd say that both these "chunks" need to be used in a (Flare) topic to set the context. The warning notice needs to be in the context of the thing you are about to do where you need to heed the warning. The chunk-topic that contains the task instructions may need links to relate it to what you have just done, or guidance about what you could do next. I can't think of many occasions where I would want to include a chunk-topic on its own, I think I would want to include an instance of a chunk-topic. And that's what wrapping it in a (Flare) topic does for you.

Incidentally, what I do is to try to write my content in as modular a way as I can, so that each section is a functionally cohesive unit that describes one thing only. I'm happy to create a Flare "article" topic containing all these sections, and leave it like that, until I discover a need to reuse one of the sections. Then I work out what belongs in the chunk-topic, and what belongs in the surrounding (Flare) topic text. Then I make the snippet (or chunk-topic). You obviously already have a need to reuse some of the sections, so you will be designing your chunk-topics and Flare topics with that need in mind.

Perhaps this helps make you feel better about it, or perhaps not.

[Carlsen]

In my thinking a snippet is something you would reuse multiple times within a single document/output (like warnings), whereas a topic is something that would only appear once within a single document/output type (because why would you repeat the same subject in multiple places in the same document/output?). The topic, however, could also appear in multiple different documents/outputs.

Maybe I am limiting myself in my way of thinking, but the difference between a topic and a snippet is all conceptual. If you create a topic and a snippet in Flare and look at the code, the html is identical (with the exception of the h1 Flare adds to the topic.) They are each complete html pages. So the difference between a topic and a snippet is only conceptual. They can mean whatever we want. So why not put a topic within another topic or a snippet in a TOC if the underlying code for each is identical? The only difference is that Flare puts a .flsnp extension on a snippet instead of .htm, which then limits what we can do on a practical level.

Dave, my point is that in Flare, you cannot combine topics and snippets equally. There is no equivalency between topics and snippets, because Flare limits what you can do with each. And why not link to a topic within a topic? I do it all the time by cross referencing to the heading of the topic.

The whole point of topic-based authoring is to do exactly what Marjorie said: chunk your information and create topics for standalone pieces of information. That's what topics are, which in my mind differentiates them from snippets in the way I've outlined above. But that's all theory. My question is on a more practical level...

So let me get back to what I'm trying to do with my Help and Installation Guide PDF and ask how anyone else would deal with it in Flare:
* When you install my product, you must add an initial user, so I want that piece of information to be in the Installation Guide.
* After the product is installed you can do the following actions on users: Add a user; update a user; delete a user, so I want all of them in the product's Help, along with information describing what users are and how they are used in the product.

So in my Flare project, I've chunked my information into four topics about users:
1. Conceptual information about users.
2. How to add a user.
3. How to update a user.
4. How to delete a user.

In my Installation Guide PDF output, I only want the "How to add a user" topic, because none of the others are relevant at the point of installation.

In my Help output, I want all of this information to be together in one Help topic so that customers don't have to go to different pages to read about each of these tasks that can be performed on users, and so that the conceptual information will be intact for each task. To me this is a usability issue: I want my customers to be able to have all relevant information in front of them so they don't have to hunt for it. In the past, I had the four above scenarios as separate output topics, and everyone complained about it.

So on a practical level, keeping in mind that in Flare you can't place a snippet within a TOC, and you can't place a topic within a topic, how would you create the four topics I have above? Would you create them as Flare topics or as Flare snippets?

My point behind this question is that no matter how you look at it, one way or another Flare forces you to do something stupid. You either have to make topics 2, 3, and 4 into snippets so you can place them into topic 1 for the Help, which forces you to create an additional topic to place the Add user content in the Installation Guide's TOC; or you have to abandon the chunking altogether and write one huge topic for the Help, which forces you to add conditional text so when you add the huge topic to your Installation Guide's TOC, only the Add user content appears in the output. I find both of these options to be inelegant solutions to a simple problem, which could be solved easily if Flare would treat topics and snippets the same, which should be easy since their underlying code is the same.

If anyone sees a hole in my argument, I'd love to hear it. There has to be a more intelligent way of dealing with such a simple scenario like the one above.

[Nita Beck]

It seems to me that you've conflated "topic" (a type of file) with "subject" (as in, subject matter). There's no rule that your four subjects have to be either all snippets (one type of file) or all topics (another type of file).

I'd create two topics and one snippet.

The snippet would contain only the procedure for adding a new user; it would not include a heading.

One of the topics would be "How to add a user," which would contain a heading as live text and the snippet; it would be on the TOC for the installation guide.

The other topic would be the longer one containing the conceptual material and the three different procedures. With one exception, everything in it would be live text, including the subheading for "How to add a user." The exception would be the snippet holding the add procedure. That longer topic would be on the Help system's TOC.

I think this simple solution is just as elegant as any other, and there's only one instance of each of the subjects (concept, add, update, delete) to maintain. No need to conditionalize anything (assuming that the Help includes only stuff that is on its TOC, so the standalone add topic doesn't get included).

[Carlsen]

Hi Nita,

There is confusion in terminology. Flare files are "topics" but tech writers also tend to call help pages "topics" as well. I was trying to make the distinction between flare topics and output topics. I'm not sure that's what you mean by "subject". But my point is that the topics we create in Flare should not necessarily be what we see in our help output. We should have the freedom to combine out topics in any way we choose, even by putting topics within topics. Obviously someone agrees with me, otherwise DITA wouldn't have this capability. And I stand by my argument about what a snippet is: It's a piece of information that does not completely cover a piece of information or "subject" if you wish. I think MadCap agrees with this definition, otherwise we would be able to put snippets into TOCs.

I have a few problems with creating the files as you suggest:
First, you're not following what we as tech writers are continuously told about topic-based authoring. A topic should completely cover a single task or concept. This is beneficial to allow the greatest reuse possible. So I believe I need at least four topics to cover the three tasks and the one concept. Breaking it up into four pieces gives me the greatest ability to reuse the information.
Second, you're creating a container topic that serves no purpose other than to get around limitations in Flare (1. cannot combine topics; 2. cannot put snippets into TOCs.)

I actually have no problem with Flare not being able to insert snippets into the TOC. This makes perfect sense to me based on how I think about snippets, i.e. they are not complete pieces of information; they are not topics. They are inserted into topics, not TOCs.

My problem is that Flare does not allow us to combine topics so that we can create output help files in the ways we want to.

I'm beating a dead horse here, because obviously Flare cannot do what I want. I also have trouble understanding why the simple solution of being able to combine topics seems unacceptable to repliers to this thread. It would clean up our lives a lot, and eliminate the convolutions required to create what we want to create. Regardless, I'm going to submit a feature request to allow us to combine topics in the TOC the way DITA allows. We'll see if MadCap thinks it's a good idea.


Thanks,
Josh

[Nita Beck]

I also have trouble understanding why the simple solution of being able to combine topics seems unacceptable to repliers to this thread.

Speaking only for myself as a replier to this thread, I have not deemed anything unacceptable. I have rather tried to be helpful by offering a solution, regrettably one that doesn't get you what you're after. Sure, it's a workaround around the limitations of Flare that you've identified. But it's a solution nonetheless, until such time that MadCap offers the method you'd prefer. (And my apology if you feel that you're not being heard... vis a vis, have been beating a dead horse.)

[NorthEast]

Second, you're creating a container topic that serves no purpose other than to get around limitations in Flare (1. cannot combine topics; 2. cannot put snippets into TOCs.)

I actually have no problem with Flare not being able to insert snippets into the TOC. This makes perfect sense to me based on how I think about snippets, i.e. they are not complete pieces of information; they are not topics. They are inserted into topics, not TOCs.

My problem is that Flare does not allow us to combine topics so that we can create output help files in the ways we want to.

Both the Flare and DITA processes allow you to combine sections of content, they just do it in different ways.

I don't think it's a problem that you can't combine topics, as you can combine snippets; and snippets can contain exactly the same content/HTML as a topic.

To me, it makes sense that you can't combine topics in the Flare environment. A topic in Flare is used in both source and output, and it's an individual and unique instance of the content.

A snippet is not unique or individual, you can have several instances of a snippet in multiple locations; so it makes sense why you cannot link to a snippet, or place it in the TOC directly.

For example, if you could use topics in the same way as snippets, then how would things like a cross-reference to a topic work? If the topic is no longer a unique instance of the content, and can be reused in multiple locations, then which instance/location of the topic would a cross-reference be linked to?

[Carlsen]

Hi Nita,

My beating a dead horse comment wasn't directed at you or the other repliers. It was directed at Flare, because obviously Flare cannot do what I want. I had hoped there was something I was missing in the product and there was a simple solution that I simply didn't know the product could do. But maybe I know the product better than I think I do. It is frustrating when you want to do something simple, but you have to make a convoluted mess out of your project because Flare cannot perform a simple task, and more frustrating when that simple solution is available in other products and frameworks, but Flare simply doesn't have the feature.

However, I do get the sense from posting to this forum and reading other posts that some Flare users have become so used to Flare's limitations that they don't stop to think whether the way Flare forces us to work is an intelligent way to work.

And Dave, I get it that you can combine snippets. But as I've said more than once, using snippets in this way creates its own set of problems and workarounds when single sourcing. It seems to me that Flare should make some attempt to make our lives easier rather than making our lives more difficult. I can only imagine how messy some projects are that have thousands of topics. I'm lucky that in my project I have less than a thousand topics, but I've heard of projects that have more than a hundred thousand topics. Can you imagine how confusing and messy that project would be if they had to do the workarounds suggested in this thread? It would be a nightmare to maintain, and impossible to hand off the project to another writer without weeks or months of explanation.

Flare can do better.


Josh