Chaps i think there's a need for a Really Good Flare book

[forfear]

A really good Flare book that covers really advanced super massive 1000 topic + projects.

I am offering to write the book.
Any ideas?
What do ya think? considering the audience of the forums and our profession, you'd imagine there'd be a tonne of writers, screencasters and books for this popular tool

In fact the book will cover how to best use Flare, structure projects, and perform regular maintenance updates with Analyzer and Lingo to generate professional print and web knowledgebases. That would super good.

[Richard Ferrell]

Sounds like a great idea, Let us know if you need any help!

[NorthEast]

Yep, learning how Flare works is one thing, but knowing how to use it well is another.

On a side note about getting started with Flare, how about being able to download full project templates as well as Flare skins?
I reckon we could do with some full project templates, so that you have a stylesheet, master pages and topic templates that go with the skin.

[forfear]

I think there's a skins download section on this site under Downloads > Skins

Other stuff would be nice would be custom Stylesheets, custom Snippets, even custom script hacks (if there is a need for these things). I can be sure madcap support is checking this site out and probably working on a 'Writers Resource' center. i.e Adobe Developer network or the Microsoft Developer Network (MSDN) .

[DocuWil]

Thank you!

That is a sound I like.
Reading the subjects in the current guides is one thing, but how to use it in practice and what you can do (tips and tricks) is another thing.

Maybe it is a good idea to write this book based on version 4 when all good stuff from Blaze is implemented.
A chapter containing topics about handling images, using MadCap's Capture or not, would be of interest I think.
I saw many topics in the forum about this subject.

Do you realize that if such a book reaches the market, it has to be updated every year? Because MadCap releases new versions at least every year.
So, maybe also a digital version to which people/customers can subscribe?

Anyway, I am looking forward to it.

Regards,
Wil

[forfear]

Look at it this way, Flare is a great product with 'depth' as, mr guy kawasaki would say about what makes great products.
Lets just hope and pray they can continue to make more good decisions than bad ones, never stop lookin for opportunities to innovate and to work with their legions of fans.

I really hope they also don't spread themselves unnecessarily thin, but so far they seem to be doin fine and are makin lots of happy people.

[AlanFisk]

There's a desperate need for a book designed for human use. Flare's own help system appears to be a loose translation from Klingon. As a new user, I'm wildly frustrated by even the most basic tasks; for example, I want to add a standard background colour to all my topics. It's probably quite a simple thing to do, but I've spent nearly an hour trying to follow the baffling instructions in the help system.

[Fedja]

What you seem to be in need of is an extended "tutorial". A help system with a finished product sample and individual steps on how to make it Help doesn't get much more understandable than that.

Aparently I'm ok with klingon I guess, I find the help solid enough. However, it's very "textual" by concept, which suits about 30% of the learning public. The other two thirds are "trial" or "visual" learners, and the tutorial approach is much better suited to them.

[forfear]

Hi
Never thought about that actually but cool idea. I was overwhelmed by the Help System as well actually. I couldn't follow the Video tutorials because they were rather sluggish or moved at too tepid a pace for me, too much user interaction required. But the Help system is good once, you've worked out and understood the flow of things, its packed with tonnes of information.

Here's how you do it.

Customer number 1
How to add a background colour to your topics
1. Before you do this add a stylesheet to your topics. Project > Add Stylesheet.
2. Attach it to any existing topics, or to the master page. With an open topic, select Tools > Stylesheet Links.
3. In Project Explorer, expand Resources > Stylesheets.
4. Edit the stylesheet in the document pane. (Basic view)
5. In the Stylesheet editor, select the Body class.
6. Select Background color.
7. Finito.

If its not clear make another post. I be here to answer any other questions..
I am not in an editing sort of mood so the steps are really coming to me as i type it.

[forfear]

Flare is awfully powerful. But to produce immediate professional results, there's a fair bit of customization, if everything has to be built up from scratch. But once, you've standardized the important things, look and feel, you just wanna copy and paste it accross your projects.
My thoughts...

How to add a background colour.
How to change a topic title.
How to apply styles to multiple topics.
How to hide topics
How to hide words and topics
How to reuse text
How to insert page numbers
How to make simple tables
How to make tables with stripes


How to organize webhelp output and produce a HTML Help system.
How to clean imported topic files from word.
How to manage images in projects.
How to have different headers and footers for different book sections

How to add an index.
How to add a cover page.
How to add a page footer and header.
How to change the web help logo.

How to insert drop down text.
How to add a cell.
How to add a list.

[NorthEast]

For me, the main areas I had trouble with weren't to do with Flare as such, but more that I needed to understand (X)HTML and CSS in order to use it and get the best out of it.

I'd used a number of authoring tools before, such as RoboHelp HTML, but they don't expose you to HTML and CSS quite so much.
When I started, I didn't know what some of the HTML tags swere (such as div, ol, ul, li, or span), and I didn't know what a CSS style class is.

In order to use Flare's editor, you need to know a bit of HTML. It took me ages to work out simple things like putting a p tag in a list in order to get an indented item without a number/bullet.

Then when you want to create your own look-and-feel to your projects, you need to really understand CSS.
I find the default MadCap stylesheet (and skins) pretty basic. They don't really showcase what you can do with Flare, and there isn't much there that you can copy/adapt for your own projects.
What I would like to have seen were a variety of good examples - projects with different stylesheets, skins, master pages and topic templates. They would show off what what I can do with Flare and give me ideas, and I could look at the examples to see how they work.

I've got to a position now where I think my project template looks good and is relatively easy to use and live with, but it took months of experimenting and learning to get there.

[forfear]

For me, the main areas I had trouble with weren't to do with Flare as such, but more that I needed to understand (X)HTML and CSS in order to use it and get the best out of it.

....
I've got to a position now where I think my project template looks good and is relatively easy to use and live with, but it took months of experimenting and learning to get there.

I hear ya..i guess we're at the same stage...i am just beginning to start generating and tooling around with the templates again after stabilizing the content.

[SteveS]

I hear ya..i guess we're at the same stage...i am just beginning to start generating and tooling around with the templates again after stabilizing the content.

If your content is stable, copy the project and play around with the copy. I found when I first started doing the formatting I got in all sorts of "pickles".

[helen]

Is it written yet? I'd like to place my order please!

[AlanFisk]

[quote="forfear"][quote="Dave Lee"]For me, the main areas I had trouble with weren't to do with Flare as such, but more that I needed to understand (X)HTML and CSS in order to use it and get the best out of it.

....
That's the problem. It seems that Flare was created by a bunch of software developers who all have ponytails, straggly beards, and broken spectacles held together with insulating tape. What it seems to lack is input from people who actually create documentation. I had been warned that Flare was extremely difficult to learn and use, and so it's proving to be.

Oh, how I want Help & Manual. I even take back all the rude things I said about AuthorIT when I was using it.

[wclass]

Clearly, we're all different ...

One of the reasons I (with my team) chose Flare is because it was EASY to use. From the first day of our trial we were up and running and generating output, and we would not go back to the other tool. The beginner's tutorial was useful, and I've learnt lots from the helpfile.

Now, we've had issues, and we had to learn stuff, I won't deny that, but I think it's in pretty good shape. Using the XML editor was different, but if you really don't like it, use one of your own choosing - in a team environment that is a plus. I don't like the CSS editor, but I can set up a .css file elsewhere and bring it into a project seamlessly.

I probably wouldn't buy a book nowadays (apart from the fact that there is no more room on my shelves). I'd rather see the Knowledge Base expanded. I don't think there is enough room in a book to cover best practices. Books tend to see things from one point of view - a knowledge base or a wiki (or a forum) can have far more examples and scenarios. I'd support the "writer's centre" concept mentioned earlier - a place to download templates, and skins, and scripts, ...

Just my two cents.

[collie]

For me, the main areas I had trouble with weren't to do with Flare as such, but more that I needed to understand (X)HTML and CSS in order to use it and get the best out of it.

....
That's the problem. It seems that Flare was created by a bunch of software developers who all have ponytails, straggly beards, and broken spectacles held together with insulating tape. What it seems to lack is input from people who actually create documentation. I had been warned that Flare was extremely difficult to learn and use, and so it's proving to be.

Oh, how I want Help & Manual. I even take back all the rude things I said about AuthorIT when I was using it.

Yes, and because I am also having to develop (not program, just (ha!) the creative stuff) a totally different application which I have to learn better than anyone else - and test to the nth degree - and then write the Help and Manual, I am finding having to learn all this stuff pretty taxing - especially when basic questions are not answered.

So, please add to your list:

1) How to change all the MadCap logos which appear in WebHelp and DotNet to my company's so that all MadCap branding is removed - it's not appropriate and would be confusing for the end user.... I'm sure you don't want to deal with our tech support as well as your own (but my dissatisfaction with that is a whole nother story)

2) How to keep those changes running under Vista, which keeps replacing the replacement gifs and bmps with the originals

3) What happens on an end user's computer when the default style sheet is used - do they see what I see? If not, why not? What is the point of setting styles and fonts etc in a style sheet if the user doesn't have those fonts? Yes, I understand about font families, but which fonts are in which families? Actually setting up a style sheet is not difficult, but without understanding what the effects will be, it's like swimming in treacle.

4) How do you get round the warning messages which pop up in Explorer when viewing WebHelp?

... and all the things other people are asking for.

[Fedja]

....
That's the problem. It seems that Flare was created by a bunch of software developers who all have ponytails, straggly beards, and broken spectacles held together with insulating tape. What it seems to lack is input from people who actually create documentation. I had been warned that Flare was extremely difficult to learn and use, and so it's proving to be.

Oh, how I want Help & Manual. I even take back all the rude things I said about AuthorIT when I was using it.

That was a bit harsh there...

From what I've seen Flare is nothing short of brilliant, if a bit hard to learn. The reason for the learning curve, however, is not in poor design, but rather in the broad spectrum of options that it offers. It's naive to assume that one could migrate from a basic, rigid, and simplified tool to a more powerful and versatile one without having to invest significant time and energy in training.

Now... I agree the way in which the functionalities of the software are presented to the user could do with a second look. It could be more friendly towards the visual learners and the people who are most comfortable around samples and examples, but don't kid yourself and think that it'll make it much easier to learn. It'll make it easier to learn for some people and not for others. At the end of the day, it's still a tool that gives you tons of freedom to create your documentation, and all that freedom comes from knowing the zillions of options and tricks that are used.


P.S.: I suggest you learn to love the guys with ponytails and straggly beards. If it wasn't for them, most of us help&documentation authors wouldn't have a job.

[forfear]

All really good comments. I am sure the Flare lads and ladies are an awfully fun bunch of people.

But it's true...
IMHO, Flare caters to the authoring professional; that expects to manage fairly modest to large projects that will have to be maintained for a fair bit of time. Its not exactly priced as freeware or shareware level, and I think the team is looking towards solving some larger problems that plague technical and documentation projects in the past, particularly from an editing and maintenance standpoint.

Honestly i could and have managed maintaining documentation projects all in Microsoft Word, if used correctly.

If you do have an organization that's purchased Flare for you recently, good for you. Its a good opportunity. Time to pick up new skills, have a cup of coffee, take notes, and keep an open mind. We're always young. The skills i've learned in Flare, particularly with CSS, will take us far into any authoring environment. If they make it easier for everyone else in the next version, good for everyone.

If it wasn't Flare i guess, i'd break my teeth into the venerable and respectable Framemaker path instead, the granddaddy of structured authoring.

In my case, I had to make my own choices, no one to make em for me.

I chose Flare because there were some things i felt could be done better i.e. such as unicode translation, and all the good stuff that comes new young products, plus all the annoying stuff as well. I gotta admit, if you look at the r***help7 interface, the ui does tend to look awfully efficient.

but alas when you dig deeper, i think flare just might have that additional edge. Its no bed of roses, but its what's been keeping me excited coming to the office recently.

PS. i only just recently made public our a portion of docs in Webhelp for our internal support teams on sharepoint. I will be breaking it down later into bite size portions for audience specific roles in PDF.

[LTinker68]

3) What happens on an end user's computer when the default style sheet is used - do they see what I see? If not, why not? What is the point of setting styles and fonts etc in a style sheet if the user doesn't have those fonts?

You have the same problem if you send someone a PDF from a Word or FM document and you didn't embed your fonts. Whether or not the user has the same fonts as you has nothing to do with MadCap and is a problem you'd also have with Word/FM output, PDF output, and web pages.

Yes, I understand about font families, but which fonts are in which families?

A font family isn't a group of specific fonts. It's simply a priority listing of fonts. So you can mix sans-serif fonts with serif fonts with Wingdings fonts, if you wanted (not that anyone would be able to read that). The last font listed in the font family should always be "sans-serif" or "serif". That way, if the user doesn't have any of the previously listed fonts, then having one of those at the end will tell the system to pick its default sans-serif (e.g., Arial) or serif (e.g., Times New Roman) font.

Actually setting up a style sheet is not difficult, but without understanding what the effects will be, it's like swimming in treacle.

I definitely suggest picking up a book or two on stylesheets. It's a trend the industry is heading toward, not away from. So you'll have to learn it at some point, if you want to keep your job.

[RamonS]

1) How to change all the MadCap logos which appear in WebHelp and DotNet to my company's so that all MadCap branding is removed - it's not appropriate and would be confusing for the end user.... I'm sure you don't want to deal with our tech support as well as your own (but my dissatisfaction with that is a whole nother story)

I agree with that, this is a discussion that goes on for some time and MadCap brought forward some reasons that I think are all without much substance.

2) How to keep those changes running under Vista, which keeps replacing the replacement gifs and bmps with the originals

Knowing how Vista works...or better to say not works I squarely blame that on the crapware that Vista is. Don't use Vista. There is not a single reason to use Vista, but many reasons not to use. This being one of them. If you still do want to use Vista, don't blame others for what Microsoft goofed up throughout five years of development.[/quote]

3) What happens on an end user's computer when the default style sheet is used - do they see what I see? If not, why not? What is the point of setting styles and fonts etc in a style sheet if the user doesn't have those fonts? Yes, I understand about font families, but which fonts are in which families? Actually setting up a style sheet is not difficult, but without understanding what the effects will be, it's like swimming in treacle.

You have to see style sheets as a friendly recommendation as to how you think the page should look like. Browsers allow for ignoring and even overriding style sheets. In some cases that is necessary to get user aiding tools to work.
Style sheets are a good thing. I don't have a handle on CSS myself, but I understand the reasoning why one should use a style sheet. Keep in mind that style sheets are designed to be used by machines. If humans were the targeted audience putting in pictures with a little bit of descriptive text will be much easier.
There is plenty of documentation out there to get you prepared for using style sheets. I also found that sticking with the Flare defaults typically works very well. I posted in a different thread that I think one can get by easily with less than a dozen styles. IIRC I came up with 8 different styles and even that was pushing it. Keep your audience in mind, does it really have any benefit to use 5 different fonts in your document that each have 28 different styles? Does the reader really figure out what the differences are and why this section of text is styled differently than that section? I am sure that most readers don't even notice that there is a difference. When in doubt follow the KISS principle for styles, it will save everyone a lot of work and confusion.

4) How do you get round the warning messages which pop up in Explorer when viewing WebHelp?

When you look at WebHelp locally you need to enable MOTW....or even better use a browser that actually works and adheres to standards, such as Firefox or Opera. Same here as what I said for Vista, don't blame MadCap for Microsoft forcing the masses to use a horrible POS called Internet Explorer. There are alternatives that are as cost effective and technologically way more advanced....and don't tend to have the security issues that require those warning messages.

... and all the things other people are asking for.

I agree with that as well, but one also has to see that MadCap doesn't have endless resources available. I submitted tons of bugs and enhancements (which I think is the same as a bug) and after discussing some of them with MadCap I come to the conclusion that my requests would make for a worse application. In some cases many reasons lead to the decision to do things the way they are, so it comes down to a case by case basis.
Announcements were made for changes in Flare 4 and many of those are based on customer requests. Rome was not built in one day they say so how can Flare, which is way more complex than Rome, be perfect and the answer to it all within a matter of a few years? I do think MadCap made some errors in the fundamental design, but even for that are plausible explanations and I can live with the outcome, BUT the MadCappers got it right in at least 95% of all issues and made it work even better than one could ever ask for. I think approaching the remaining 5% with constructive criticism will eventually make those problems go away as well.

[collie]

From what I've seen Flare is nothing short of brilliant, if a bit hard to learn. The reason for the learning curve, however, is not in poor design, but rather in the broad spectrum of options that it offers. It's naive to assume that one could migrate from a basic, rigid, and simplified tool to a more powerful and versatile one without having to invest significant time and energy in training.

Now... I agree the way in which the functionalities of the software are presented to the user could do with a second look. It could be more friendly towards the visual learners and the people who are most comfortable around samples and examples, but don't kid yourself and think that it'll make it much easier to learn. It'll make it easier to learn for some people and not for others. At the end of the day, it's still a tool that gives you tons of freedom to create your documentation, and all that freedom comes from knowing the zillions of options and tricks that are used.

Quite - it's not poor design, but there is a high degree of assumption in the explanations. For those of us who parachute in from time to time and have to get a job done, then some basics and some well-presented examples are what we need, so I think Forfear's idea of a book is a really good one.

Certainly its versatility is what attracted me, but it's not always clear how to choose which path and when.

[collie]

I agree with that, this is a discussion that goes on for some time and MadCap brought forward some reasons that I think are all without much substance.

Very restrained! Seriously, though, if I can't crack this, then in the end the Help will have to be built and powered by something else - which will make me cross because as a freelance I have to bear the cost of wanting it to work.

Knowing how Vista works...or better to say not works I squarely blame that on the crapware that Vista is. Don't use Vista. There is not a single reason to use Vista, but many reasons not to use. This being one of them. If you still do want to use Vista, don't blame others for what Microsoft goofed up throughout five years of development.

[/quote]

Yeah, yeah, heard all that from the DOSsers when Windows first appeared ... but it's also head-in-the-sand stuff.

The harsh reality is that you can't buy a new computer off the shelf that doesn't have one or other version of Vista on it. That means that our new end users have Vista, and our existing customers will upgrade at some time or another, so in turn that means that our application has to run on Vista and has to be tested rigorously on Vista... and that means that I have to have Vista on my computer, so if I'm doing screen shots etc for the Help, then my developers would like it to look up to date.

There is plenty of documentation out there to get you prepared for using style sheets. I also found that sticking with the Flare defaults typically works very well. I posted in a different thread that I think one can get by easily with less than a dozen styles. IIRC I came up with 8 different styles and even that was pushing it. Keep your audience in mind, does it really have any benefit to use 5 different fonts in your document that each have 28 different styles? Does the reader really figure out what the differences are and why this section of text is styled differently than that section? I am sure that most readers don't even notice that there is a difference. When in doubt follow the KISS principle for styles, it will save everyone a lot of work and confusion.

Yes, this is pretty much the approach I am adopting. I've wasted too much time trying to learn everything about CSS in between doing all sorts of totally unrelated things, so am starting off with the default and making little changes here and there so it doesn't look like a clone of MadCap help!

When you look at WebHelp locally you need to enable MOTW....or even better use a browser that actually works and adheres to standards, such as Firefox or Opera. Same here as what I said for Vista, don't blame MadCap for Microsoft forcing the masses to use a horrible POS called Internet Explorer. There are alternatives that are as cost effective and technologically way more advanced....and don't tend to have the security issues that require those warning messages.

Oh, Vista drives me potty! I have to have UAC turned on because of testing the program, but several times a day I do find myself screaming abuse at the monitor.... " I am a Administrator!!" "Yes!! I am sure I want to do this!!"
So, no, I don't blame MadCap..... except that they advertise their program as being Vista-compatible. When we have users complaining that this or that doesn't work in Vista, we investigate and if we can, we provide a fix. If there's no fix, we see if we can find a way around.... and we don't make claims about compatibility, just that it will run provided certain precautions are taken.

agree with that as well, but one also has to see that MadCap doesn't have endless resources available. I submitted tons of bugs and enhancements (which I think is the same as a bug) and after discussing some of them with MadCap I come to the conclusion that my requests would make for a worse application. In some cases many reasons lead to the decision to do things the way they are, so it comes down to a case by case basis.
Announcements were made for changes in Flare 4 and many of those are based on customer requests. Rome was not built in one day they say so how can Flare, which is way more complex than Rome, be perfect and the answer to it all within a matter of a few years? I do think MadCap made some errors in the fundamental design, but even for that are plausible explanations and I can live with the outcome, BUT the MadCappers got it right in at least 95% of all issues and made it work even better than one could ever ask for. I think approaching the remaining 5% with constructive criticism will eventually make those problems go away as well.

Yes, you're a good advocate for them, Ramon, and broadly I agree with you. We too do a great deal for our customers, but we don't bury things we don't know the immediate answer to, nor do we disguise fixes and updates as major upgrades....but on the whole I am not displeased either with the program or the interface, or I wouldn't be here! I hope they have listened to customers for Flare 4 because some gripes (not all are bugs, some are design faults) really do need to be taken seriously.

[Richard Ferrell]

In regards to the Issue with the Logo, The Logo can be removed in Webhelp, For more information please see the following KB article.

http://kb.madcapsoftware.com/default_CSH.htm#OUTW1009F

If the Dot not help is embeded into your dot net application then the splash screen will not appear, Hopefully the option to remove this will be in the next version.

[KevinDAmery]

That's the problem. It seems that Flare was created by a bunch of software developers who all have ponytails, straggly beards, and broken spectacles held together with insulating tape. What it seems to lack is input from people who actually create documentation. I had been warned that Flare was extremely difficult to learn and use, and so it's proving to be.

So what do you make of the push from technical writers to use XML standards like DITA? You want complicated, well... (And no, it's not the tool vendors who are pushing that onto poor defenseless TWs--if you don't believe me, go check the TechWR-L archives.)

The big thing these days is to be standards compliant and not use proprietary formats (like .doc and .fm for example). Madcap has adhered to the XHTML standard precisely because you can edit its files with other tools if you have to. (Good luck getting files out of Authorit without using Authorit to do the export, for example--by comparison, I can edit my Flare source in Notepad or Dreamweaver if I have to....) More than that, going to XML and XHTML gives organizations the option to perform data translations on the source to produce output in multiple formats and for multiple products / applications / whatever.

Sure, CSS takes some effort to learn, but saying that using it makes Flare a bad tool is completely off base.

Oh, how I want Help & Manual.

Last I checked (about a year ago) H&M also uses HTML and stylesheets, plus a healthy dose of java script. Not to say H&M is a bad tool (I liked it, to be honest) but don't think that it's going to completely insulate you from the big bad world of markup code and CSS.