Custom toolbar and custom appearance

[MarinaMichaels]

My client is creating a developer support site for their products. For all new documentation, they have asked me to use a Wiki instead of Flare. We are keeping the current reference documentation in Flare format, but they would like the Flare output to look less help-like.

Issue #1: Custom Toolbar

My client would like me to replace the current WebHelp toolbar with a navigation bar, similar to the one on this page (this isn't my client; just an example):

http://developers.freshbooks.com/overview/

I've searched the KB but didn't find anything on this. Looking at Flare itself, I see that there is a place to include custom JavaScript. Is that the only way to get this look?

Issue #2: Custom Appearance

In addition, my client would like to make the WebHelp output look as much like the output on the Freshbooks page above as possible.

1. They want the divider between the navigation bar and the topics to be minimized in size. Is that possible?
2. They would ideally like the divider to go away entirely. Is that possible?
3. They really would like to completely get rid of the accordion navigation and just have links for the TOC and index. Is that possible?

Also, if some of you can come up with some good, solid reasons for keeping the documentation in Flare format, I would appreciate it.

Thanks for your help, and happy holidays to all!

regards,

Marina

[carolynmwallace]

First, my best shot at an argument for keeping things in the current Flare format: Users know what Help files are supposed to look like. Why confuse them by presenting Help in a format that looks no different from a website? Also, is it possible the user will get confused between what's the application and what's the Help?

OK, putting that aside for the moment, I think everything you ask about CAN be done. I'm not sure, however, I have the BEST way to do it. What you'll be doing is customizing the skin of your Flare project, but I've been looking and I can't quite find a way to do certain things in Flare itself (I'm hoping a Flare guru will help us out). Looking at the issues from my former Web designer viewpoint, however, I know they can be done since Wikis and Flare WebHelp outputs are basically web sites.

Issue #1: Custom Toolbar. When you generate the Flare output for WebHelp, you end up with an Output folder. FIRST THING: Make a back-up copy of this folder!!! Just in case any of this doesn't work out, you know.

Now look in the Output folder for the Skin Folder. Inside the Skin folder is one called Images. Here you'll see the graphics Flare uses to create the toolbar appearance. You can replace these with your custom graphics. Important: Make SURE you use the same names/graphic formats that Flare does. For example, you'll find Flare graphics called "Home.gif," "Home_over.gif," and "Home_selected.gif." These all show the little house on the toolbar in its various states. Replace them with your own "Home.gif," "Home_over.gif," and "Home_selected.gif" (and repeat for all the other toolbar icons) and you'll have customized your toolbar graphics.

Once you have the custom images you MIGHT have to open Toolbar.htm (Skin > Toolbar.htm) in order to make size adjustments to the HTML code. From reviewing the Toolbar.htm in my project, I don't think you will, as it appears the image sizes are not hard-coded, but keep in mind this might be a possibility.

Issue #1: Custom Appearance. It should be possible to make the dividers go away. In HTML-speak, what you want is a frameset with invisible frames. Unfortunately, I've been going over everything in my Output folder and I can't seem to make the darn things disappear! There may be something in the background that I'm just missing; I hope someone else on the forum will be able to tell us BOTH how to do this!

I can tell you how to eliminate the undesired accordion items within Flare: In the Project Organizer, open the Skins folder and click on your skin. On the Basic tab, you'll see "Features." Clear all the check boxes except for "Table of Contents" and "Index" and you'll have at least limited the accordion navigation to just those two topics. I can't see a way to change the accordion appearance to just links, however, without getting far more into HTML and JavaScript than either of us want to go.

Good luck and let us know how it goes!

[RamonS]

One good solid reason is also that anything custom means more work now and during maintenance. Unless the customization is direly necessary (such as customer won't pay for anything if there is no custom toolbar in the help) I'd stay away from it and probably play around with it on a side project or at home. Also, anything that gets customized has to be fully documented. What if you get a coworker to take over the project while you are busy with something new? If everything is documented the changeover will be easy, otherwise the coworker needs training or will ask many times for help so that you end up doing both projects. Furthermore, customization makes something to be unique. Any errors that may be introduced may not be able to be solved in a common, established, and known to be working way.
I do understand that customization intends to take something and make it better, but if the standard does as well then why change anything? Same with style sheets. We know that the defaults work, so changing as little as possible will make for a much stabler project and way less hassle.

[MarinaMichaels]

Thanks for the helpful replies. I agree that if we do anything custom that has to be manually done, we shouldn't do it. However, there is a box for entering JavaScript for the toolbar--that is probably our only choice aside from, perhaps, having the header at the top of each topic page instead. Less optimal, but at least it gets the links in.

The documentation I am creating isn't actually help; it is instead just that--documentation; specifically, an API Developer's Guide. That part is staying in the help format because I was very persuasive about it. I may have even cried a little. (Not seriously!) I did talk about user familiarity and learning styles, as well as how interconnected everything is, and how much time it would take to convert over it all over to Wiki pages.

We are also creating a user's guide for the application that the API supports, and yes, that is intended to be the help file for the application and therefore the argument for being in help format is stronger.

However, the person in charge of the project, an engineer, doesn't like the help format and instead wants use Wiki/HTML pages for the user's guide/help. I would rather use Flare, but for the context-sensitive help, it should be possible for the developers to create links to the Wiki pages that open the pages in a pop-up browser window or in another tab. I'm willing to work with this; in fact, I am looking forward to it. It will be an interesting experiment, and if nothing else, if it doesn't work, I should be able to convert the pages into a Flare project fairly readily. And although it is a Wiki, our customers will only have read (not write) access to it.

regards,

Marina

[RamonS]

Sounds like a feature request to me: use Flare to populate the most common Wiki systems with content. IIRC I asked for this some time ago. Wikis become more and more popular as collaboration tool. And the Wikimedia Wiki is set up in a few minutes and the markup they use is very easy (one can also allow XHTML to be used). Since this is all open source it should be fairly easy to have Flare attach it to...not saying that this isn't a lot of work.
You know where to file feature requests? If not, go here: https://www.madcapsoftware.com/support/bugs/submit.aspx

[NorthEast]

However, the person in charge of the project, an engineer, doesn't like the help format and instead wants use Wiki/HTML pages for the user's guide/help.

I don't think the decision on using a wiki should be based on how its output looks, it should be based on how you want to write your content. Since a wiki is a collaborative authoring tool, the main point here is who is actually going to write and edit the content?

If you want the readers/users of the API documentation to be able to edit and contribute to the content, then you need a wiki to do this - you can't do this with a help ouput.

If it's just you that's writing the content, then you don't need a wiki - you use the tool that is best for the job, i.e. Flare or whatever you want to use.

[carolynmwallace]

However, the person in charge of the project, an engineer, doesn't like the help format and instead wants use Wiki/HTML pages for the user's guide/help. I would rather use Flare, but for the context-sensitive help, it should be possible for the developers to create links to the Wiki pages that open the pages in a pop-up browser window or in another tab.

The final output for Flare WebHelp is HTML pages (technically XHTML/XML, but check your Output > Contents folder: 99% HTM files or other Web-supported formats such as JS and XML files). Flare can also create the context-sensitive Help links you're looking for right in those pages.

All your developer really dislikes is the LOOK (i.e. "format"), right? And since the readers will NOT be able to edit content (like a Wiki), standard Flare HTML pages should be fine.

Am I totally off-base in thinking all of this can be done in Flare...the customized look, etc.? I'm thinking you set up the skin/images once, and then the project can generate the needed HTML pages whenever. You wouldn't have to customize it each time.

[RamonS]

I think Dave really hits the point. Who generates the content and who is in charge of maintaining it? If it is to be a collaborate effort Wiki seems to be the way to go. If not, I'd tell the developer to worry about the code and leave the documentation efforts to the tech writer.

[MarinaMichaels]

After some discussion, it looks like we are going to use Flare to create the user's guide after all. At least, that's the plan this week.

The look and feel: I am a contractor, which gives me less weight in these discussions. I think Flare is a great tool for documentation, for many reasons, including the ability to easily create links between subjects that are updated automatically when you make most types of changes. The Wiki is for presenting information and is not intended to be edited by our users; instead, I and other people at the company will be generating the content. However, the developer still wants the Wiki look. He doesn't like anything about Flare, especially the WebHelp appearance. He doesn't want the way the navigation bar looks, and he would like the tool bar, search, favorites, and index to go away completely. I explained that different people use different ways to access content in documentation (TOC, index, browsing, search). I also explained to him that the index is something that I, a professional indexer with many years of experience, created by inserting the index entries in the topics. But he remained unconvinced that anyone would use the index, search, or favorites capabilities.

I think if I could get Flare to generate output that has a navigation sidebar with no borders or accordion, just a TOC, he would be happy with the Flare output. But I don't know how to do that, which is what my original post was asking about--is it possible, and if so, how?

[RamonS]

And why did that company hire you then? I mean, they get an experienced tech writer on board under contract and then have a developer decide how the documentation looks like? Maybe you should make some proposals since the GUI of the application doesn't look right. Stuff like that just drives me nuts. I hope you adjust to it better than I would.
What exactly does that developer not like? WebHelp doesn't look geeky enough? And what about users not going to use search. Search and a good index make all the difference. I could see that one drops search in favour of a good index, but not both.

[carolynmwallace]

First, the good news: a customized toolbar, no accordion items, and no frames CAN BE DONE (see image below).
Now, the bad news: I could only complete it by hacking the HTML code in the output files. Maybe that's because I'm using Flare 2.5; maybe 4.0 has more skin options?

Anyone know a skins expert who could walk Marina through doing this all in Flare? Because my way is definitely a pain and would require extra steps with each content update.

[KevinDAmery]

I always hate to hear about these kinds of cases. Some engineer or developer comes down with Wikiphilia and then everything has to be a wiki whether it makes sense or not.

“Wikiphilia: A mental illness characterized by the irrational conviction that any problem faced by a group can be rendered solvable through installation and use of a Wiki. This delusional ailment has been occurring in increasing numbers ever since it was first identified in 1995. Wikiphilia usually manifests in two distinct phases - the rapturous anticipation of the Wiki’s potential in the short post-installation phase; slowly giving way to denial of the Wiki’s failure to fulfill that potential in the second phase. …”

[RamonS]

If it really has to be so bare bones with no frills and anything that makes WebHelp a help system then either use a Wiki or just link independent pages together. That written, I recommend to not fall for such pointless requests and point out the benefits of full-text search and proper indexing as well as the low maintenance work when using a stock setup. What does the BA or product manager have to say about this? After all, it should be their call or the one of the tech writer, not the one of the developer.

[MarinaMichaels]

First, the good news: a customized toolbar, no accordion items, and no frames CAN BE DONE (see image below).
Now, the bad news: I could only complete it by hacking the HTML code in the output files. Maybe that's because I'm using Flare 2.5; maybe 4.0 has more skin options?

Anyone know a skins expert who could walk Marina through doing this all in Flare? Because my way is definitely a pain and would require extra steps with each content update.

That's exactly what we want! But, as Carolyn says, can someone tell me how to do this? Can this be done using JavaScript in the custom JavaScript box? Many thanks!

regards,

Marina