MadCap Software Forums

Hello,

I'm trying to find out what are Flare's CMS capabilities in order to design and structure the contents we want to use.

We produce different software tools with some common functions between them (and thus common contents between the different printed guides). At the moment, each development team (and the technical authors for each tool) work like islands. We have user guides written in Word and we want to start using an authoring tool. So we would transfer all the information in these manuals to the authoring tool and use it also to create context sensitive online help.

Let’s say that we use Flare's capabilities to have some simple content management system. The idea would be to place text and image elements (sometimes a whole topic, sometimes something as small as a paragraph or even a sentence) in a common porepository in an unstructured way. Then the authors would retrieve these unstructured elements to structure their documents or online help projects. But the only way to make this properly work is to tag all those pieces of information. For retrievability and reusability purposes, I would need to tag each element (maybe with metadata?) so that people know:

• * To which software tool is the element associated
  * What is the intended audience of the element (engineers, normal users, etc.)
  * What kind of help is the element providing (user guide, reference material, installation guide, marketing, etc.)
  * For what kind of output is the element intended for (online help, printed manual, training material, etc.)
  * Etc.

Is such a system compatible with Flare? Is there a way to tag the different elements so that they can be easily retrieved and used accordingly?

TIA,

Dnaiel

And if such a system is not possible, is there another way to properly organize the information?

Please note that we are just about to start using Flare, so we don't really have any experience on this. I'm just trying to figure out the best way to organize the contents so that authors can benefit from the work of their colleagues when updating or creating new manuals/guides/online help projects.

Thanks,

Daniel

Do check out the video demo of Flare if you can Dan, on the madcapsoftware website.

* To which software tool is the element associated
* What is the intended audience of the element (engineers, normal users, etc.)
* What kind of help is the element providing (user guide, reference material, installation guide, marketing, etc.)
* For what kind of output is the element intended for (online help, printed manual, training material, etc.)
* Etc.

But in short, Flare, an XML based authoring tool. It does what you're looking for although I wouldn't go so far as to categorize it as a Content Management System per se. It excels as a single-sourcing and authoring environment that generates multiple outputs that can be repurposed accordingly.

Yes - You can use condition tags and tag paragraphs to exclude/include from specific targets.
Yes - You can use condition tags and tag images to include/exclude them from specific targets.
Its a XML based documentation and help authoring tool.

Its used by
technical writers, process document writers, development/training/financial/services/learning organizations
to create all kinds of documentation (user guide, reference material, installation guide, marketing, etc.)
in multiple formats (PDF, Doc, chm help, Web Help, Mobile formats (documentation that can be read on mobile devices /iphone)
for multiple audiences from a repository of topics.

That covers a number of different areas; you'll probably want to read-up on the following:

* Snippets: You can set up a snippet containing a chunk of content, and then re-use it inside other topics.

* Global project linking (i.e. a Flare project import file): If you have shared content that you want to re-use in a number of projects, you could maintain content in one project and then re-use it in a number of other projects by using a project import. Then if you change the original content, you can easily update it (automatically or manually) in all your other projects.

* File Tags: You can create your own tags and use them to mark any file in the project, e.g. a topic, snippet, image, TOC, glossary file, target. This is for files only, you can't use file tags to mark content inside a file. File tags are just for information-only; e.g. to record details like the author or status.

* Conditions: You can create your own condition tags and use them to mark any file or content within a file. You can then exclude/include content marked with a condition from the output (in the target settings). You can also set snippet conditions for topics, allowing you to control a snippet separately to the target condition settings. Conditions can also be used with a project import, i.e. you can choose to import files marked with a certain condition.

here are some other relevant forum topics:

http://forums.madcapsoftware.com/viewto ... 12&p=67666
http://forums.madcapsoftware.com/viewto ... 13&t=11871

I love the fact I created a forum topic relevant to this discussion.

Thank you for your answers. I'm quoting David because his answer is the closest to what I'm trying to find out.

The first person wrote that Flare is XML-based. Does this mean you can use metadata as tags for each topic? I don't mean exclude/include conditions (as in "exclude this image or text from this output and include it in this other output). I mean structuring the topics or snippets or whatever in such a way that they can be conditionally searched. E.g., I am looking for topics about X subject that are related to Y tool, that are meant for Z audience, and so on. Is that possible?

We now have 15 or more Word manuals, ranging from 100 to 600 pages each. I need to feed all these manuals into the system (the authoring tool), but I don't want to feed them as complete manuals; rather, I want to break each manual into, say, 300 or 500 large or short topics and provide the authors with the capacity to look for any information related to what they are intending to write about, so that they may find something that someone else already wrote and is 90% similar to what they intend to write and thus reuse it.

Does that make any sense? Or am I making a mistake in treating it as a parallel CMS and I should structure the info in another way?

Thanks,

Daniel

Dave Lee wrote:That covers a number of different areas; you'll probably want to read-up on the following:

* Snippets: You can set up a snippet containing a chunk of content, and then re-use it inside other topics.

* Global project linking (i.e. a Flare project import file): If you have shared content that you want to re-use in a number of projects, you could maintain content in one project and then re-use it in a number of other projects by using a project import. Then if you change the original content, you can easily update it (automatically or manually) in all your other projects.

* File Tags: You can create your own tags and use them to mark any file in the project, e.g. a topic, snippet, image, TOC, glossary file, target. This is for files only, you can't use file tags to mark content inside a file. File tags are just for information-only; e.g. to record details like the author or status.

* Conditions: You can create your own condition tags and use them to mark any file or content within a file. You can then exclude/include content marked with a condition from the output (in the target settings). You can also set snippet conditions for topics, allowing you to control a snippet separately to the target condition settings. Conditions can also be used with a project import, i.e. you can choose to import files marked with a certain condition.

When you import your manuals, they can be split up into as many smaller pieces/topics as you want (automatically done by heading, or manually done after the import). if you create webhelp that includes all of your topics, you will be able to use the webhelp Search capabilities to find keywords, etc. i have a CMS of all my manuals (1 PDF manual linked in each topic) with "metadata" at the top in each topic that i manually typed in - such as published date, keywords, document owner, title, etc.

are your writers going to all have access to Flare and write there manuals from there? another way that i have used Flare to make a webHelp CMS is through a database of all my company's RFP response answers. I made individual topics for each answer, and my users/writers can search the webhelp for what they are looking for, copy and paste from there/the browser, and insert into their RFP Word doc. (They do not have Flare access.)

I wouldn't necessarily use the search features inside the Flare software like i would in webhelp. there's too much extra content in a flare project that wouldn't be relevant.

have you been able to accomplish this type of CMS with another software? why do you think it should be this way?

Thank you for your answer. Let me try to address your points.

lacastle wrote:When you import your manuals, they can be split up into as many smaller pieces/topics as you want (automatically done by heading, or manually done after the import). if you create webhelp that includes all of your topics, you will be able to use the webhelp Search capabilities to find keywords, etc. i have a CMS of all my manuals (1 PDF manual linked in each topic) with "metadata" at the top in each topic that i manually typed in - such as published date, keywords, document owner, title, etc.

I'm not talking about the final user to be able to find things using the search tool in the webhelp system. I'm talking about authors being able to find content written by other authors in the company, about authors being able to find, retrieve and reuse content.

But if one can add its own metadata at the top of each topic, that should be enough for my purposes, right? I mean, just add some keywords so that other authors can find the topics related to whatever they are authoring. How do you achieve this? Do you have to create some sort of metadata definitions somewhere else in Flare?

lacastle wrote:are your writers going to all have access to Flare and write there manuals from there? another way that i have used Flare to make a webHelp CMS is through a database of all my company's RFP response answers. I made individual topics for each answer, and my users/writers can search the webhelp for what they are looking for, copy and paste from there/the browser, and insert into their RFP Word doc. (They do not have Flare access.)

Yes, all writers are going to use Flare. We will buy a few licenses and have all the authors work on Flare. At least that is our plan right now. But we certainly want to give access to all the contents to other people in the company who will not be using Flare, such as marketing and management people, so that they can retrieve some contents for presentations and so on.

lacastle wrote:I wouldn't necessarily use the search features inside the Flare software like i would in webhelp. there's too much extra content in a flare project that wouldn't be relevant.

?

lacastle wrote:have you been able to accomplish this type of CMS with another software? why do you think it should be this way?

We have never had a CMS system in the company. I just wanted to know if Flare could provide some essential CMS management for help documentation.

Also... is there a place where I can see how to map Flare topic IDs to C Sharp (Windows Forms)??? I would very much appreciate this info.

Thanks again,

Daniel

I don't think that Flare is going to provide what you're looking for here, at least not well.

Is this the type of scenario you are envisioning? Writer Jane has been assigned to create a manual for product X. Product X shares some features and concepts with other products in your company's product suite, but Jane doesn't necessarily know which other products and what has already been written. So she needs to search for "widgets" and see what other content is already out there, so that she can see what might be reusable within her new manual. And in the "widget" search results she needs to see information like what type of content it is, who wrote it or "owns" it, when it was last updated, etc.

The search capabilities within Flare itself are not so good and are targeted more toward "search and replace" editing rather than finding content based on keywords and metadata. I have used a CMS system before in the type of scenario described above and Flare is just not intended to do such things. You might be able to use an intelligent folder structure so that writers could browse and find stuff they need, and you could manually tag topics with things like the author, but I think it would be a little like forcing a square peg in a round hole if you really want robust CMS searching and metatagging capabilities.

Have you bought Flare yet?

This seems like a situation where the sales rep could earn their keep, showing you how Flare can work for you. That way they can answer your questions as they pop to mind...

One thing you might consider is commenting your topics. You can create a paragraph style for comments (so they're obvious - I use a green background) and using conditional tags prevent the comments from being included in any of the build targets. You can use the find function within Flare to look for keywords or phrases so therefore search your comments.

I wonder if you would be advised to use source control, Flare is not a CMS as such, although plenty of people seem to use it for contenet management in a defacto way. Source control would allow the team to share documents without treading on one another's toes.

HTH

sniper_de wrote:But if one can add its own metadata at the top of each topic, that should be enough for my purposes, right? I mean, just add some keywords so that other authors can find the topics related to whatever they are authoring. How do you achieve this? Do you have to create some sort of metadata definitions somewhere else in Flare?

You might find that file tags are suitable for this to some extent. For example, you might define file tags for author, product/tool, version, audience, etc. Then for each file you can choose any number of these preset tags.

You can view the tags in the File List, and also generate reports for file tags (by each individual tag).


Note that whatever method you use, any search/report in Flare will just list files for the current project; you'll not get results from separate projects.

whunter wrote:I don't think that Flare is going to provide what you're looking for here, at least not well.

Is this the type of scenario you are envisioning? Writer Jane has been assigned to create a manual for product X. Product X shares some features and concepts with other products in your company's product suite, but Jane doesn't necessarily know which other products and what has already been written. So she needs to search for "widgets" and see what other content is already out there, so that she can see what might be reusable within her new manual. And in the "widget" search results she needs to see information like what type of content it is, who wrote it or "owns" it, when it was last updated, etc.

Yes, exactly.

whunter wrote:The search capabilities within Flare itself are not so good and are targeted more toward "search and replace" editing rather than finding content based on keywords and metadata. I have used a CMS system before in the type of scenario described above and Flare is just not intended to do such things. You might be able to use an intelligent folder structure so that writers could browse and find stuff they need, and you could manually tag topics with things like the author, but I think it would be a little like forcing a square peg in a round hole if you really want robust CMS searching and metatagging capabilities.

So is there any workaround (or working with a second tool) you would recommend for this kind of scenario?

Thanks,

Daniel

SteveS wrote:Have you bought Flare yet?

This seems like a situation where the sales rep could earn their keep, showing you how Flare can work for you. That way they can answer your questions as they pop to mind...

One thing you might consider is commenting your topics. You can create a paragraph style for comments (so they're obvious - I use a green background) and using conditional tags prevent the comments from being included in any of the build targets. You can use the find function within Flare to look for keywords or phrases so therefore search your comments.

But as Dave says, this would not work across projects, right?

SteveS wrote:I wonder if you would be advised to use source control, Flare is not a CMS as such, although plenty of people seem to use it for contenet management in a defacto way. Source control would allow the team to share documents without treading on one another's toes.

HTH

Thanks,

Daniel

Someone else here suggested to use some sort of metatags on each topic. Something like:

<author>Bla bla</author>
<date>blab la</date>
<tool>Bla bla</tool>
<output>blab la</output>

Does Flare allow for something like this?

Would the authors be able to search these metatags across projects?

Daniel

Dave Lee wrote:

sniper_de wrote:But if one can add its own metadata at the top of each topic, that should be enough for my purposes, right? I mean, just add some keywords so that other authors can find the topics related to whatever they are authoring. How do you achieve this? Do you have to create some sort of metadata definitions somewhere else in Flare?

You might find that file tags are suitable for this to some extent. For example, you might define file tags for author, product/tool, version, audience, etc. Then for each file you can choose any number of these preset tags.

You can view the tags in the File List, and also generate reports for file tags (by each individual tag).

Note that whatever method you use, any search/report in Flare will just list files for the current project; you'll not get results from separate projects.

So there's no way to search for keywords or anything like that across projects? Is this only an issue with Flare or is it the same with Robohelp?

Thanks,

Daniel

sniper_de wrote:

Dave Lee wrote:

sniper_de wrote:But if one can add its own metadata at the top of each topic, that should be enough for my purposes, right? I mean, just add some keywords so that other authors can find the topics related to whatever they are authoring. How do you achieve this? Do you have to create some sort of metadata definitions somewhere else in Flare?

You might find that file tags are suitable for this to some extent. For example, you might define file tags for author, product/tool, version, audience, etc. Then for each file you can choose any number of these preset tags.

You can view the tags in the File List, and also generate reports for file tags (by each individual tag).

Note that whatever method you use, any search/report in Flare will just list files for the current project; you'll not get results from separate projects.

So there's no way to search for keywords or anything like that across projects? Is this only an issue with Flare or is it the same with Robohelp?

You create predefined search filters in WebHelp when authoring.
That would help you narrow the search down for different audiences and meet the needs of your target audience.
To sharpen search results you can also specify synonyms.
See what search filters look like at the following link
http://webhelp.madcapsoftware.com/flare6/Default.htm
- Click the Search tab. See the Filters box below the search box.

Search synonyms work when you have MadCap Feedback

http://webhelp.madcapsoftware.com/flare ... xample.htm

On this page, Step 1, after 3. Select Tools>Concept>Concept Window or press SHIFT+F9 on your keyboard. The Concept window pane opens, there is a little down arrow with the word Example in green. How is this function/button called in Flare? And below this sentence, there is a sort of preview miniature of a screenshot. If you hover the pointer over it, you get the big picture. How is this function called?

Thanks a lot!

Daniel

forfear wrote: You create predefined search filters in WebHelp when authoring.
That would help you narrow the search down for different audiences and meet the needs of your target audience.
To sharpen search results you can also specify synonyms.
See what search filters look like at the following link
http://webhelp.madcapsoftware.com/flare6/Default.htm
- Click the Search tab. See the Filters box below the search box.

1. Do these filters work across projects?
2. Are they only meant for the help output or also for the authoring phase?

Thanks!

Daniel

sniper_de wrote:On this page, Step 1, after 3. Select Tools>Concept>Concept Window or press SHIFT+F9 on your keyboard. The Concept window pane opens, there is a little down arrow with the word Example in green. How is this function/button called in Flare?

That is a toggler.

sniper_de wrote:And below this sentence, there is a sort of preview miniature of a screenshot. If you hover the pointer over it, you get the big picture. How is this function called?

That's a thumbnail.

Both togglers and thumbnails are described in the Flare help.

sniper_de wrote:Would the authors be able to search these metatags across projects?

No. The find/replace features in Flare's editor can only search content in the current project.


The references to both search filters and synonyms above are not relevant to your question; they're features you can add to your help output, and are nothing to do with finding content whilst authoring in the editor.

LTinker68 wrote:

sniper_de wrote:On this page, Step 1, after 3. Select Tools>Concept>Concept Window or press SHIFT+F9 on your keyboard. The Concept window pane opens, there is a little down arrow with the word Example in green. How is this function/button called in Flare?

That is a toggler.

sniper_de wrote:And below this sentence, there is a sort of preview miniature of a screenshot. If you hover the pointer over it, you get the big picture. How is this function called?

That's a thumbnail.

Both togglers and thumbnails are described in the Flare help.

Thank you very much. What are the RoboHelp equivalents to togglers and thumbnails?

Daniel

It's been a long time since I used RoboHelp, but there is a good Flare for RoboHelp Users manual in the Flare help menu (Guides).

Thanks to all of you for your valuable help. Much appreciated!

Daniel