Canvassing for one-click interface

[forfear]

this is my first time doing this..but lets see how the community feels about this ...

I've noticed on days when I am working purely in Flare, by the end of the day, my right hand starts to tire very easily. My clicking fingers feel numb. I was wondering if you sometimes feel the same, that much more could be done to reduce the number of clicks to get to many things in Flare. Don't get me wrong, its a great single-sourcing package, responsive support, helpful community and when cohesive feel when used as a suite as well. Robust, single-sourcing. The style picker is great. flare is growing up to be a handsome young teen.

Each new version has lots of subtle enhancements, in the past, such as user friendly topic linking and snippet insertion which are top notch.
However, i find that there are still way a lot of clicks, to get things done.
I open topics, close topics, locate snippets, insert snippets, images, open tocs, etc..switch targets
in the course of a heavy day, particularly with new projects, i might open/close to 40 topics, rebuild the target about 20 times, insert conditions/crop screenshots, etc, adjust TOC about 15 times. in the course of this, you might resize the Project Organizer, and then flip back to Content Explorer. in alll these, you'll also be expanding the content and project tree many times, all of which take 4 clicks each, expand,locate item, double-click to open.

anything that takes the amount of physical stress away from repetitive clicks, and 'smoothens' the authoring experience would be great. so its not necessarily keyboard shortcuts for everything. perhaps steps that could be bypassed.

Here's my proposition
In the course of these few weeks, to consider submitting bugs/enhancements to the madcap dev team with particular regards to improving the most common authoring workflows (only if it makes sense to you)
- TOC editing/structuring
- drag and drop was world-class. but with a keyboard for common indenting/demoting topics, for the thought process, magic happens.
- shortcuts for making chapters and section markers in toc
- sync topic title to link toc topic title (in case topic title changes, toc should change)
- Topics
- one-click to open
- snippet/variable/condition pickers
- rearrange lists with shortcuts
- word editing shortcuts, line deletion, word deletion,
- Page layouts
- Images/Object Manipution

Any ideas or AHA! experiences you may have had with heavy duty tools not necessarily from HATT tools are always great eye openers. These fixes are tiny, micro changes, some you won't notice immediately but could make a big physical in day to day authoring experience in the long run as you work with more projects.

and yes, i won't have to replace the left mouse and right mouse clicker by year end

[forfear]

i've logged a few of requests in the last few months, but was afraid i might be alone in this.

[Andrew]

I've actually considered making a thread very much like this one for the past few months, and, like you, specifically because of the number of clicks it takes to get to snippets, variables, and conditions. I've come up with two possible solutions, but those solutions actually go pretty far beyond simply addressing the issue of clicks.

Most Recently Used / Most Frequently Used
Provide a pane / dialog / tool palette (whatever you call them) that contains two lists (like the Index Entry pane that contains both the index fields and the condition tags -- alternatively, MRU/MFU could be two separate panes): one that contains a list of MFU (most frequently used) objects, and on that contains a list of MRU (most recently used). This dramatically reduces the clicks involved in two common types of use case:

Case 1: Snippets / Variables / Conditions Used Often
There are certain snippets, variables, and / or conditions we use frequently. For example, I created snippets out of a couple of types of tables and notes that I frequently use (I insert them, then convert to text and customize). I have also learned, through the pain of several product name changes (and company name, in the case of acquisition), that it is wise to insert the company and product names using variables, so I frequently use the CompanyName and ProductName variables.

In the existing Flare functionality, that means that whenever I want these things, I either have to insert them using the menus (where, typically, they are 5+ clicks, scrolls, etc. away). There are two problems with this: 1) it takes too much time and effort to click that many times for something you use over and over. Multiply the clicks by how many times per day I have to insert a table or company name or product name, and it comes out to be a lot. 2) Having to click through all of those menus *takes me out of my content* -- takes me out of the thinking mode I'm in while writing. If all I had to do was double-click in a tool to insert a variable, that would be much less disruptive. With the change I am suggesting, it would be, at most, 1 or 2 clicks. Flare should keep track of those objects I use most often, and "stick" them to the MFU area so that I have my most frequently used objects at my fingertips.


Case 2: We Use the Most Recent Condition / Variable / Snippet Multiple Times
Many times when I am applying a condition or a variable or snippet (though especially conditions), I will apply the same one multiple times in a short time frame, even if that one is not frequently used. For example, I have a condition tag for feature 45651, and I now want to apply it to all the content I just wrote that is applicable to 45651. Even though I don't often use that condition tag, in this specific instance, I use it a dozen times.

In the existing Flare functionality, this means that I have to apply the condition multiple times, going through the same menus and clicks each time. After the 10th time click Format > Conditions > Release12 > (scrolling) > 45651, I'm ready to rip out my hair. If 45651 appeared at the top of my MRU list as soon as I used it, then each time I apply a condition, it is only one click, and I move quickly and happily through my work.


Other interesting things to consider: ability to "pin" certain objects to the menu, similar to what you have for the Windows Start menu, MRU and MLU should probably not share any objects (maybe?), ability to invoke MRU/MFU via hotkey, sort of like the Style Picker.

This is getting a bit long, so I'm going to continue my next idea in the next post.

[Andrew]

Snippets Are Merely Topics
When trying to create a good single-sourcing project, I've stumbled over the extremely limited management for snippets. You can organize them by folder in the Content Explorer, but this has only the affect of changing the list order (grouping snippets by folder in the Insert Snippet Link dialog). Any list of snippets which goes beyond a couple of dozen quickly becomes very inefficient to use and aggravating to manage. There are a lot of ways to help with this (improve the management of snippets, such as forfear's suggested Snippet Picker, make a "find as you type" style searching of the lists of snippets, etc.). However, I think that there is a better way to do this which really makes snippets out to be what they are:

Snippets are topics!

I don't mean that in the theoretical Tech Writing way; I mean that in the Flare way. The differences between a snippet and a topic seem very superficial to me. Both contain CONTENT that you produce for your users...except that snippets are gimped in that they cannot stand alone, and they are very difficult to manage.

That's all a long way of getting around to saying: ditch snippets completely and enable us to insert a link to any topic into another topic and have it behave just like a snippet.

Use Cases: Snippets Are Hard to Manage
(I'm relatively certain that one could quibble over various details of the case below, but I hope that as a whole, my point is clear.)
Say I have a release I am documenting that contains 100 features. I produce an New Features Guide which contains deep and broad information on each feature, a Feature Benefit Guide which is light marketing that contains a description of each feature and its benefits, and I produce online help which contains conceptual, reference, and step-by-step task information. Each feature is a topic unto itself, and each topic has a general description, conceptual overview, procedures, screen reference material (for field definitions, etc.), and list of benefits, all of which I turn into snippets, because:

- I will use all the information together as an entry in the New Features Guide.
- I will use the desciption and benefits for the Feature Benefit Guide.
- I will break apart many of the snippets for the online help -- description, conceptual information, and benefits may go together still, but procedures and reference info will have their own topics.

Currently in Flare, I would have to create "shell topics" for each of these different instantiations of content, and then fill them with snippets (and some other text where necessary). This means I have to manage 100 x (from 5 to 10 snippets per feature) snippets, or 500-1000 snippets -- for just 1 release, for a produce which will contain MANY releases over its life. Using the current snippet functionality, this is a nightmare, having to scroll through hundreds of snippets in the Insert Snippet Link, and having to go deeeeep into the Resources\Snippets structure in the Content Explorer, and make many of my own folders, which are COMPLETELY APART from the "shell topics" I'm using to create content.

If all snippets were simply topics, I could create a folder for every feature at the root of the Content Explorer (or under several more general categories), and inside that folder I would have *all the content* I need for that feature. My management system is the same one I use for all the rest of my content (which, by the way, could use some improvement...ah, another feature suggestion for another day ). I could also create fewer of the "shell" topics, and leave those bits of content that stand alone, alone.

[Andrew]

To respond a bit more specifically to you, forfear:

- shortcuts for making chapters and section markers in toc
- sync topic title to link toc topic title (in case topic title changes, toc should change)
- Topics
- one-click to open
- snippet/variable/condition pickers
- rearrange lists with shortcuts
- word editing shortcuts, line deletion, word deletion,
- Page layouts
- Images/Object Manipution

I'd support pretty much all of these on a general level, but I would have to see the specifics to decide if I really want any one thing done. But I really like the idea of snippet/variable/condition pickers (fits right in with a lot of my thinking on those objects, which are currently a pain to use repeatedly).

[KevinDAmery]

Currently in Flare, I would have to create "shell topics" for each of these different instantiations of content, and then fill them with snippets (and some other text where necessary).

No you don't.

What I do is, write the topic that contains all the content that will be made into snippets first, as a standard topic. Then I select the blocks that will be part of a snippet and use the Make Snippet function, telling Flare to replace the existing content with the snippet.

This has a few advantages:

• It means I can do all my writing in one stream, which keeps me focused
• It means I don't have to pre-create snippets or topics to use as chunks
• It means I don't have to muck around with assigning stylesheets, master pages, etc. to each chunk
• It means I don't even have to decide which bits are going to be reusable chunks until after I have the content written, so I can see where the breaks make the most sense

I also name the snippets so that they're easy to find (for example, anything that has to do with reporting has Report as the first part of the name).

Moving on to the larger point, the main problems I see with using htm files instead of snippets for your chunks are 1) that htm have more metadata baggage (for example, stylesheet links, namespace declarations, javascript links, head tag sets, etc.) which adds complexity when it comes to inserting them in another topic, and 2) the danger of someone adding a "snippet topic" directly to a TOC by mistake because they thought it was a "full" topic.

Honestly, though, I've never found tracking down the snippets I need to be that onerous. I have a few hundred of them in my largest project, but it doesn't take me any more time to find them than it does a standard topic. My .02 at any rate....

[KevinDAmery]

We really should be able to just drag and drop variables and snippets into a topic. I can't see why they haven't implemented that (yes, I have requested it... more than once....)

[Andrew]

This is the sort of debate I was hoping to avoid when I created that use case...I was hoping the point would shine through any of the implementation details: snippets are content. Topics are content. Why do I have to use two different areas and two different "objects" to manage my content?

Currently in Flare, I would have to create "shell topics" for each of these different instantiations of content, and then fill them with snippets (and some other text where necessary).

No you don't.

What I do is, write the topic that contains all the content that will be made into snippets first, as a standard topic. Then I select the blocks that will be part of a snippet and use the Make Snippet function, telling Flare to replace the existing content with the snippet.

I know I can start with one long topic, and then snippetize that (which is one way to approach the issue), but you'd still have to insert the snippets into other "shell" topics for each individual procedure, for concept-benefit topics for the help, for the Feature Benefit Guide, etc. Part of the point of single-sourcing is to be able to easily reuse content. Snippets make that relatively easy at a micro level, but very difficult (and overly-complicated) on a larger scale.

This has a few advantages:

• It means I can do all my writing in one stream, which keeps me focused
• It means I don't have to pre-create snippets or topics to use as chunks
• It means I don't have to muck around with assigning stylesheets, master pages, etc. to each chunk
• It means I don't even have to decide which bits are going to be reusable chunks until after I have the content written, so I can see where the breaks make the most sense

I agree with the first two points -- they are advantages. However, your second two points don't make much sense to me -- the 3rd because I almost never apply master pages, style sheets, etc. to any piece of content after the fact -- I do it either at the target level, or in the Add Topic dialog when I create the topic. The 4th is a non-issue if you are pursuing any kind of significant structured authoring. Which bits are going to be snippetized are already definied before you write a thing.

Moving on to the larger point, the main problems I see with using htm files instead of snippets for your chunks are 1) that htm have more metadata baggage (for example, stylesheet links, namespace declarations, javascript links, head tag sets, etc.) which adds complexity when it comes to inserting them in another topic, and 2) the danger of someone adding a "snippet topic" directly to a TOC by mistake because they thought it was a "full" topic.

Snippters already can have most or all of that in the code. Flare simply ignores it when inserting the snippet. I don't see how a "full topic" is different. Even if it is, just piggyback the existing snippet insertion process.

Honestly, though, I've never found tracking down the snippets I need to be that onerous. I have a few hundred of them in my largest project, but it doesn't take me any more time to find them than it does a standard topic. My .02 at any rate....

It's not so much the time it takes to find them (though that is a pain), as it is that all my content for 1 feature should be in the same place. Snippets are content...why treat them differently?

[Andrew]

We really should be able to just drag and drop variables and snippets into a topic. I can't see why they haven't implemented that (yes, I have requested it... more than once....)

You can already do that...just navigate to the Snippets folder in the Content Explorer and drag-n-drop.

But wouldn't it be much easier to drag-n-drop if the snippet was right next to your topics in the Content Explorer?

[LTinker68]

But wouldn't it be much easier to drag-n-drop if the snippet was right next to your topics in the Content Explorer?

I organize my topics into folders anyway, so I'm always going down at least one level. That said, it would be nice if I didn't have to go down two levels to get to the snippets. On the other hand, I understand why they're differentiated from topics. You can only have one topic with a specific file name, therefore it's not reusable content. A snippet file can be used in multiple topics, so it's by definition reusable. (Adding a topic to the TOC in two places doesn't count as reusable content.)

I would like a pane, similar to the Index Explorer, where reusable content (variables, snippets, glossary terms, index keywords, etc.) are categorized in the pane so that I can expand a group (or leave them all expanded) and then drag-and-drop whatever item I want into the topic that I'm writing in. I've asked for user configurable keyboard shortcuts in the past for specific variables in the variable set, but I think I like the idea of the pane more.

[KevinDAmery]

We really should be able to just drag and drop variables and snippets into a topic. I can't see why they haven't implemented that (yes, I have requested it... more than once....)

You can already do that...just navigate to the Snippets folder in the Content Explorer and drag-n-drop.

But wouldn't it be much easier to drag-n-drop if the snippet was right next to your topics in the Content Explorer?

It's been a while since I tried it (version 2.x) but last time I tried dragging a snippet into a topic, it created a hyperlink rather than inserting the snippet.

And the snippets are in the content explorer: Content\Resources\Snippets. Not really seeing your point there....

[KevinDAmery]

This is the sort of debate I was hoping to avoid when I created that use case...I was hoping the point would shine through any of the implementation details: snippets are content. Topics are content. Why do I have to use two different areas and two different "objects" to manage my content?

'Cus they're used differently for different purposes. For example, images, audio, flash movies, etc. are also content, but no one wants to glom them all in the same folder as the htm files. And how about master pages and page layouts? Should they be topics too? They have an XML structure like a topic or snippet....

Currently in Flare, I would have to create "shell topics" for each of these different instantiations of content, and then fill them with snippets (and some other text where necessary).

No you don't.

What I do is, write the topic that contains all the content that will be made into snippets first, as a standard topic. Then I select the blocks that will be part of a snippet and use the Make Snippet function, telling Flare to replace the existing content with the snippet.

I know I can start with one long topic, and then snippetize that (which is one way to approach the issue), but you'd still have to insert the snippets into other "shell" topics for each individual procedure, for concept-benefit topics for the help, for the Feature Benefit Guide, etc. Part of the point of single-sourcing is to be able to easily reuse content. Snippets make that relatively easy at a micro level, but very difficult (and overly-complicated) on a larger scale.

This has a few advantages:

• It means I can do all my writing in one stream, which keeps me focused
• It means I don't have to pre-create snippets or topics to use as chunks
• It means I don't have to muck around with assigning stylesheets, master pages, etc. to each chunk
• It means I don't even have to decide which bits are going to be reusable chunks until after I have the content written, so I can see where the breaks make the most sense

I agree with the first two points -- they are advantages. However, your second two points don't make much sense to me -- the 3rd because I almost never apply master pages, style sheets, etc. to any piece of content after the fact -- I do it either at the target level, or in the Add Topic dialog when I create the topic.

I use a lot of classes in my stylesheet. If you're writing a snippet separately, in order to have those classes available in the style window you need to link to the stylesheet.

The 4th is a non-issue if you are pursuing any kind of significant structured authoring. Which bits are going to be snippetized are already definied before you write a thing.

You're telling me your product specs never move on you after you've started developing the documentation? Mine sure do....

Honestly, though, I've never found tracking down the snippets I need to be that onerous. I have a few hundred of them in my largest project, but it doesn't take me any more time to find them than it does a standard topic. My .02 at any rate....

It's not so much the time it takes to find them (though that is a pain), as it is that all my content for 1 feature should be in the same place. Snippets are content...why treat them differently?

Already mentioned this one above: images, movies, master pages, stylesheets, etc. are all content too. I prefer to keep them segregated, though.

And, while snippets may have the same xml structure as a topic, they aren't the same thing from a writing perspective. A topic has a complete logical flow and must contain the full amount of information needed to inform the reader. A snippet otoh is just a component, and is not (usually) going to be standalone. (I put the "usually" in there because some people create topic-sized snippets to get around the issues that crop up if you use the same htm file twice in a TOC... which is a bit of a special case, and not what most snippets are used for.) If you keep the "complete" topics and the "little bits" topics all in the same place and with the same extension, it's going to get difficult to tell which is which.

[Andrew]

This is the sort of debate I was hoping to avoid when I created that use case...I was hoping the point would shine through any of the implementation details: snippets are content. Topics are content. Why do I have to use two different areas and two different "objects" to manage my content?

'Cus they're used differently for different purposes. For example, images, audio, flash movies, etc. are also content, but no one wants to glom them all in the same folder as the htm files. And how about master pages and page layouts? Should they be topics too? They have an XML structure like a topic or snippet....

Right, but none of those things is text. Snippets can be used for different purposes, but they also don't have to be (except as they are now, this comes with a lot of annoying baggage). I have no problem separating out non-text, as it is not text, and it's something you don't edit with Flare; rather, you insert them when appropriate. Snippets are text content. They are the same information you put in topics, albeit in most cases in smaller chunks with a different file extension. Master pages, page layouts, CSS files, pictures, movies, sounds, etc. are not the same.

Before I respond any further, is this an issue of you not seeing my point, or of seeing it but disagreeing? If it's the former, I'm happy to continue to explain why I think snippets=topics=snippets is a good idea, but if it's the latter, I'm not particularly interested in debating the issue -- I'd rather not run away with forfear's topic, which I think is very much a worthy pursuit and something I'd love to see the entire community get involved with, and a debate between you and me is likely to keep people at bay.

[LTinker68]

Don't focus on what content is in a snippet versus what's in a topic. Focus instead on reusable versus non-reusable. Sure, you can put a topic in the TOC twice, but you're not really reusing the content -- you're merely repeating it. Snippets, however, let you reuse content, even to the point of the content meaning one thing (or being used one way) in one topic and in a totally different way in another topic. For instance, say you show screenshots in your topics -- or at least list the fields and buttons in the screenshots. Each (or most) of the screens may have Ok, Cancel, and Apply buttons. Now in each topic, you could retype the same definition of what the Ok, Cancel, and Apply buttons do, or, you could put the definition of each button into its own snippet file. Then in the topics that show or list the fields and buttons of a screenshot, you insert the appropriate snippets into those topics. So ScreenA may have an Ok and Cancel button so you only inserts those two snippets, but ScreenB may have all three buttons, so you insert all three snippets.

Likewise, you may have lists in topics explaining the steps a user may go through to get to a specific screen to perform a certain function. The first three steps in those topics may always been the same, telling the user what URL to go to, to insert the username, to insert a password, etc. You can put those three steps into a snippet and insert that snippet into various topics, with the remaining steps in the process being unique to each topic, depending on what the process is.

That is the purpose of snippets -- it's to reuse content in multiple topics. Doesn't matter what the content is. Could be text. Could be images. Could be images with image maps. Could be a PDF file embedded as an object so that you can view the PDF in the topic without launching Adobe Reader externally. And if you make a change to a snippet, that change will filter down to all topics that call that snippet, which is also something that topics can't do. (To put it another way, snippets are library objects.)

So... Snippets are not the same things as topics, although in your workflow they may seem that way.

[forfear]

Two thumbs up
when flare's indexing workflow appeared, it made lots of ind vets stand up and notice.
Style picker.
Multi-class formatting in one click. nice! the simple lets you select many related class items, for those TOC1,TOC2,TOC3, or h1,h2,h3, h4 scenarious, and apply formatting to all of them in one fell swoop. i don't think there are many products that let yo do that. i don't think even word lets you do that. what an ace!

TOC view
anyone use Word's outline view? the principles are a little similar for long authoring
- promotion/demotion of toc topics in a toc is the most elemental task in toc structuring. key short it, i say
- abstraction, an outline/toc view is all about drillng in and out of your topic/toc structures. sometimes you want to see more, see less. more subtle control of TOC expansion/collapse works magic.
let me see all level 1 topic,/ level 2 topics, level 3 topics only or all levels.
- gimme more subtle toc expansion, because sometimes the toc levels will indicate to you that i might want to make 70% of it into new chapters/section breaks. key short it, i say

its still early days, but every tweak has a built-in multiplier effect when you have more assets to manage every single day.

[KevinDAmery]

Before I respond any further, is this an issue of you not seeing my point, or of seeing it but disagreeing?

The latter: I see where you're coming from, but personally I disagree. (Stuart Smalley voice: "and that's... ok")

Now, could the insert snippet interface be made more streamlined? Sure, and I'd be all for it. But I think that removing snippets as a unique content type is a bit drastic as a solution to an imperfect interface.

But yeah, I think we've covered both sides of this issue pretty well at this point. (We now return you to your regularly scheduled thread.)

[forfear]

one more thing about reuse with snippets.
With a snippet you can combine a string of variables together or another snippet.
variables are standalone reuse units. a variable cannot include another variable.

[Andrew Heard]

One-click on the shift-ctrl-H style picker please. Gets me every time - can't see the point of double-click on a shortcut action.

[forfear]

I just remembered, if you turn on Intellisense there's a lot that you can use.

Keyboard shortcuts
CTRL +1, CTRL +2 , CTRL +3 should give you access to some useful stuff.

[royj]

I've noticed on days when I am working purely in Flare, by the end of the day, my right hand starts to tire very easily. My clicking fingers feel numb. I was wondering if you sometimes feel the same, that much more could be done to reduce the number of clicks to get to many things in Flare.

I'd settle for Madcap doing more to support those of us who use keyboards to navigate. Many areas within Flare are woefully inadequate when it comes to using the keyboard to move around and select options.

The biggest problem is that most dialogs are missing keyboard accelerators for the buttons and options. These are the underlined letters that show up when you press the Alt key, indicating that you can use an Alt+[letter] combination to select those options.

Getting the focus where you want it in the multi-pane Flare environment is a problem as well. I have Find and Replace, Find in Files, Index Entry, and Styles docked on the right side, but I have yet to figure out a way to open any of them up without using the mouse. If there was a way to do that, plus Alt+[letter] in place globally, I would be a happy camper.

[forfear]

In the Styles pane (accessible via shortcut F12)

pressing the Edit Styles brings up the Stylesheet Editor.

I was wondering if it would be nice to just load up the selected style in its Properties dialog box for editing. that would save some time

[forfear]

how about ALT+LEFT click to open topics directly.

this could be applied to Content Explorer, Project Organizer and even TOC editor,

That;s a lot of mouse clicks

[KevinDAmery]

In the TOC ctrl+click already opens topics (I use this all the time because I find it easier to locate my topics in the TOC than in the content explorer due to the logical structure and the naming conventions).

[forfear]

In the TOC ctrl+click already opens topics (I use this all the time because I find it easier to locate my topics in the TOC than in the content explorer due to the logical structure and the naming conventions).

i almost agreed. but if i am not wrong its a CTRL+double click to open the topic.

[KevinDAmery]

Could be. To be honest, I changed the behaviour of mine while back so that I just have to double click on an item without any modifier keys to open the topic. You can do this with the icon at the far right of the TOC window.