MadCap Software Forums

One would think that a help authoring tool would have spectacular, easy to use and easy to navigate help. Instead, what we see is a help system much like any other--topics that might make sense to some but most of the persons unfamiliar with the product are puzzled, a search tool that does not handle booleans well, and answers to questions are, well, not there.

So, I am starting a thread where we list our pet peeves with help and hopefully the folks who develop the helf will hear, learn, and incorporate appropriately.

For instance, in Flare right now, this message appears when I import a project from VSS Source control:
Creating missing directory file:///C:/Users/(snip)/Project/Users/(myname)/...
What is this message trying to convey? I do not even know if this is a problem! What will happen when I create a build? Why does the message conclude with three dots at the end; it does not even list the directory file it creates! Concerned, I go to the Help. The help is, well, no help at all. I do not understand why I have to perform a forum search in an effort to discover what a message means, and truncated messages mean nothing. There are no hits when I look in these forums either, but that is a different issue.

So, what would you like to see done to Flare Help, to make it more...helpful?

I'd like them to avoid adding the same three- to four-paragraph snippets in every related topic (the second topic looks familiar, and by the third topic, I think it's Groundhog Day!).


Good luck,
Leon

I think it is more a problem with the message itself. I'm on MadCap for years to implement some usable error reporting rather than showing useless messages like this one or barfing up whatever cryptic crud the .NET runtime comes back with. I also wonder why it is still referred to as "directory". Microsoft (senselessly) renamed that to "folder" ages ago.
A more useful help would surely be beneficial, but there is much to be said about not even needing to go to the help.

but there is much to be said about not even needing to go to the help.

hahahahahahahahahaHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHA!

Stop it, you're killing me!

Evergrey21012 wrote:One would think that a help authoring tool would have spectacular, easy to use and easy to navigate help. Instead, what we see is a help system much like any other--topics that might make sense to some but most of the persons unfamiliar with the product are puzzled, a search tool that does not handle booleans well, and answers to questions are, well, not there.

So, I am starting a thread where we list our pet peeves with help and hopefully the folks who develop the helf will hear, learn, and incorporate appropriately.

For instance, in Flare right now, this message appears when I import a project from VSS Source control:
Creating missing directory file:///C:/Users/(snip)/Project/Users/(myname)/...
What is this message trying to convey? I do not even know if this is a problem! What will happen when I create a build? Why does the message conclude with three dots at the end; it does not even list the directory file it creates! Concerned, I go to the Help. The help is, well, no help at all. I do not understand why I have to perform a forum search in an effort to discover what a message means, and truncated messages mean nothing. There are no hits when I look in these forums either, but that is a different issue.

So, what would you like to see done to Flare Help, to make it more...helpful?

use RoboHelp and look at Adobes help. think there are holes here....

chunkee wrote:

Evergrey21012 wrote:One would think that a help authoring tool would have spectacular, easy to use and easy to navigate help. Instead, what we see is a help system much like any other--topics that might make sense to some but most of the persons unfamiliar with the product are puzzled, a search tool that does not handle booleans well, and answers to questions are, well, not there.

So, I am starting a thread where we list our pet peeves with help and hopefully the folks who develop the helf will hear, learn, and incorporate appropriately.

For instance, in Flare right now, this message appears when I import a project from VSS Source control:
Creating missing directory file:///C:/Users/(snip)/Project/Users/(myname)/...
What is this message trying to convey? I do not even know if this is a problem! What will happen when I create a build? Why does the message conclude with three dots at the end; it does not even list the directory file it creates! Concerned, I go to the Help. The help is, well, no help at all. I do not understand why I have to perform a forum search in an effort to discover what a message means, and truncated messages mean nothing. There are no hits when I look in these forums either, but that is a different issue.

So, what would you like to see done to Flare Help, to make it more...helpful?

use RoboHelp and look at Adobes help. think there are holes here....

This is kinda my point...anyone who knows MadCap knows why this company was created...I had hoped that the mistakes of the past were not recreated here. At my office, we have a direct pipe between the dev folks and the doc folks where every single error message created in the software team MUST be accompanyed by a help description. In fact, bug reports are filed if an error message is too cryptic, even IF there is an associated help file! For the money we pay, I hope the "better team" to provide us with better help.

The majority of the error messages seen in Flare are from the .NET runtime. Do you see any Microsoft help that covers these? Not disagreeing that the errors should not be there in the first place and I am sure that the MadCap devs can do a better job. In their defense, .NET is a rather flaky runtime. Many of the errors do not tell anyone anything, including developers. That makes it difficult to describe the errors.

I think Flare's Help beats the pants off the Help for other tools that I've used (Word, FrameMaker, RoboHelp). Heck, when I was comparing tools a couple years ago, I couldn't even find a topic in the Author-IT Help for how to create a TOC or an Index! I've generally been able to answer most of my standard "how do I do X?" questions from the Help.

I don't really expect detailed troubleshooting information in the Help, because often you don't know what kind of trouble people are going to get into until after you release a product. And I have yet to work with a product that actually documented all possible error messages. But I'm grateful that we've got an active user forum to help out with that.

(BTW, while trying to solve my .NET error message issue today I compiled a list of solutions I found -> http://forums.madcapsoftware.com/viewto ... 13&t=15191

I think Flare's help is okay, though it's far from state of the art. It tends to be a bit too long and rambling, and the silly MadCap logo watermark that they add to every page makes it that much harder to read. Also, I believe the Flare help was written by a contractor who's not even located in their offices (last I heard, the writer was located at the opposite side of the country). That could also be a factor.

I like the Flare Help. 9 times out of 10 it answers my question without too much jumping around between topics. I'd be chuffed if all the Help I'd written over the last 20+ years was as useful. And in all that time I've never worked for a company that wanted its error messages documenting.

Simply being able to search the help for a given U.I. element's roll-over text would be very helpful.

For example, the Ribbon I'face —> Home —> Paragraph area, Group button. The roll-over text states the tool / button will "Group selected items".

Not being sure what, exactly, this meant, I tried searching Flare's help system for Group and Group selected items. In both cases I received a list of opaque topic titles for topics that didn't seem to have anything to do with the Group button / tool. (It got even weirder when I tried wrapping the search term in quotation marks, ala "Group selected items" — the Help system returned a single topic titled "Creating Relationship Tables".)

So I resorted to opening a topic in the XML editor to enable the button, then clicking Group.

Oh! — it opens the Create Group tool. I can use to apply Blockquote, DIV, Fieldset or similar tags to related items.

Armed with my newfound knowledge, I then tried searching Flare help for Create Group tool. Still no useful results, or at least no results that I could identify as useful after viewing the first two or three topics returned in response to my search…

Note that I have submitted and Enhancement Request that suggested roll-over text, tool name, and help system search all correspond…

Cheers & hope this helps,
Riley
SFO

They're developers, not tech writers (TW). It's not news that developers and TW have different priorities and different opinions on what information is "necessary".

Example:
Developers wanna play with new toys every time, which leads to x new features which are not tested thoroughly because the testing department doesn't have the resources and the developers don't do any testing because their "opus" is, of course, just PERFECT!
And:
TW are dependent on what developers let them know in time for the release. If the flow of information has rubbish quality and writing specifications comes next to castration on the feeling-awful-scale then the TW is not left with a chance.
And:
Tech writers who would prefer to make existing features easier to handle or easier to understand are boring and nerve-racking in the eyes of "true developers".

At least that's the vast majority of my experiences with software developers and I'm in the IT business for 30 years. - I just don't think, MadCap developers are really different from those I came across.

And (to not blame it all on the developers):
Sometimes there are TW who just wanna go on the way they always went and who don't respond well to changing something ...

BUT:
I also think that the Flare help is the utterly best I ever saw. Adobe help or the help of SAP R/3 for example are ... @! &+*~

I think the real discussion here is measuring the true value of Help systems in general, especially when written under the typical timeline/resource/scope constraints of all software development projects. Those constraints seem to define the ultimate quality of whatever is produced.

Otherwise, it's very difficult to objectively critique Flare Help. Lately I have become dependent on Flare Help to get up to speed with the product, and it is a refreshing experience to be a neophyte user looking for answers (rather than a Help author on a project team). All I can say is that, for the most part, Flare Help contains the answers that I seek, and navigating it isn't too terribly cumbersome.

Could I do a better job writing Flare Help myself? Hard to say. Depends on the scope/timeline/resources allocated to the project.

I have personally met MadCap's technical writer several times. He's an employee, not a contractor (though I mean no disrespect to contractors, given that I'm self-employed!), he's been with the company since it was founded (or close to it, I'm pretty sure), and he is indeed a technical writer, not a developer.

Although I can find my own batch of complaints about Flare's documentation, I chalk it up to this: MadCap's tech writer works under the same kind of demands that I do: trying his best to crank out as much stuff as he can, and as useful stuff as he can, under the constraint of working with a team of software developers on what I presume to be demanding corporate deadlines. I just envy him one luxury that he has over me: Direct access to the Flare developers!

Nita Beck wrote:under the constraint of working with a team of software developers on what I presume to be demanding corporate deadlines

Managers do that sort of stuff - especially with a direct competitor to fight (in this case: RoboHelp)

I remember reading an article just a few weeks ago - about the release of a study from a big management consulting company (named "Kienbaum"). That study mainly says that the demands and expectations of managers are too often far too high to achieve. The short-term effect on company staff is stress and frustration and, if it persists, the long-term effects are: loss of efficiency, precision and - most important - commitment/motivation.

Flare 8 is the first version of Flare that received really bad reactions - visible on these forums.
Let's just hope MC managers have learned that lesson and that gives the TW the chance to correct the things that went wrong because of lack of time, information and nerves.

i-tietz wrote:Let's just hope MC managers have learned that lesson and that gives the TW the chance to correct the things that went wrong because of lack of time, information and nerves.

And extend the beta period so they have time to receive responses from beta testers and implement some of the issues the beta testers discover, time which the TW can also use to verify that he's put everything in that he wanted to put in.

Hey, Nita, was it just one TW for all the MadCap products? If so, poor guy, since they tend to release updates for several products at the same time.

And provide a beta of the help as well. The first time anyone saw the V8 help was in the release.

I would echo some of both + and - comments so far, with emphasis on the weak Help Search feature that returns scads of topics without any weighing.
That is my biggest gripe, but it is not unique to Flare - unfortunately when I produce CHMs for our software, that search is junky too - the search engine in compiled help is a covered wagon on the information superhighway.

Conversely, the search that Flare put into the HTML 5 webhelp is pretty shiny. I showed it to our devs in a re-skin of our web client help and they were smiling.

Early on, what I wanted most was info that would tell me what CSS properties had no effect on an object, without having to do trial and error to try to find out how to autonumber something weird for example. I have muddled through since then, so it is not so big a deal anymore, except when something new comes along like the Table Continued feature, and it is hard to figure out how to get it to work with the table stylesheets we already have, which did not use caption styles because of the problem with caption bookmarks and cross-references.

Overall I like Flare help and have found only minor flubs over multiple releases. I think there is too much repetition as noted, especially when covering CSS simple and advanced, though at least it is usually in drop-downs so you can skip it.

LTinker68 wrote:Hey, Nita, was it just one TW for all the MadCap products? If so, poor guy, since they tend to release updates for several products at the same time.

On the couple of occasions I met him, I'm pretty sure he was the only TW. I have no idea if he's still the lone writer.

I think the Flare help is really very good. I have a lot of respect for the tech writer - we are an exceedingly critical audience! 90% of the time I can find the answer I'm looking for with helpful examples are the harder concepts. The rubbish search is not his fault, it infuriates me with my own help as well (and I dare say the customers). I found one typo in a video last year for Flare, and if that's my biggest gripe then I think he's doing really very well!

i-tietz wrote:

Nita Beck wrote:under the constraint of working with a team of software developers on what I presume to be demanding corporate deadlines

I remember reading an article just a few weeks ago - about the release of a study from a big management consulting company (named "Kienbaum"). That study mainly says that the demands and expectations of managers are too often far too high to achieve. The short-term effect on company staff is stress and frustration and, if it persists, the long-term effects are: loss of efficiency, precision and - most important - commitment/motivation.

Care to share the article?

Here is the article...I hope you read German: http://www.kienbaum.de/desktopdefault.a ... ead-12228/