I am moving several large databases from Aperture to Adobe's Lightroom (fwiw, I'm going to use Capture One Pro to convert and develop my fine art photos). I am (was?) an Aperture Certified Pro, and have several KMacros I used regularly. These are not complex — but they are also not annotated. What I want to do is annotate each Action which does something I no longer remember (e.g.: "⌃⌘5"), and then create new KMacros (as needed) for Lightroom.
What is the best way (easiest & most useful) to annotate KMacros? I know only two ways, neither of which I'm yet finding useful. The "Comments" Action works, but takes up too much space and isn't by default (or without using yet another Action) attached to an Action. The Notes available via the new-in-KM7 "Set Notes" command from the Action Menu could be quite useful ... is there any way to show it as a pop-up, overlay, or ToolTip? Right now it is — afaict — buried in and only revealed in the Action Menu.
Instead of adding a Comment action you can also edit the title of the action itself. So you can replace the default title with something more meaningful.
To do so right-click the action and choose Rename…:
Tom's suggestion is super. That's all I need for my task at hand.
Collapsed renamed Comments works well, too.
For the "Note" attached to an Action to be useful (as I envision using it) it must be more readily retrieved. Perhaps a thin circle around the gear icon to indicate that there is a note attached to that Action, and then display the text of the note like a ToolTip when the mouse curser hovers over the gear icon?
I make no pretense of having thought this through .
I personally don't find the Action "Note" to be very useful.
I am finding that most of the time I can rename the Action to provide the info I want, or if more info is needed, then put it in a collapsed Comment Action.
Also, instead of using a Comment Action to identify a block of Actions, I now put them in a Group Action, and rename the Group accordingly.
…just like comments in normal text scripts. If exaggerated, readability will suffer from over-commenting. So I only use it when necessary (most KM actions are pretty self-commenting).
As a header…
…at the beginning of the macro, containing some general information and metadata. I think this is the best usage for the Comment action.
Renaming actions
My preferred way when I see the need to briefly comment an action. However, I think when posting macros on the forum it might be confusing for novice users, since the action is no longer clearly identifiable by its title. Not sure though.
Grouping actions and renaming the group
A very good thing, but only when the group really is a (semantic) group.
Set Note… in the gear menu
In theory the cleanest way to comment individual actions. The gear icon turns blue when a note is set, but nonetheless I tend to overlook notes later. And it’s too complicated to read the note; as already mentioned by others, a tooltip display would be helpful.
Tom — that matches my experience and use almost completely. I'll add that I also use color to distinguish hierarchy. Which color is not meaningful in my system — but I do color the Actions so that no Actions at adjacent levels are the same color. This makes long KMacros much easier to read, ime.
The other difference is something I'd forgotten: the bluing of the Action Menu icon (the "gear") has never worked in a way I've been able to use. This post Gear Icons in Actions indicates that the blue Action Menu icon indicates not only if there is a note, but also if there are "additional parameters". Since the Actions "Type a keystroke" and "Insert Text" always have additional parameters (to name just two very common Actions), using blue to indicate also that a Note has been attached as — afaict — useless. Those Actions have no indication whether or note a note has been attached.
Here is a blue Action Menu icon for an Action that has no note:
I have already gone back and commented several macros using your recommendation to change the Action title. Very useful. It's now part of my standard practice. Thanks again.
Technically, the Set Note menu item is ticked if there is a note, so there is an indication, but not before you click.
But yes, the Note is designed to be a relatively subtle method of documenting. As noted (ha), there are other less subtle ways depending including Comments, Renaming, and color coding, depending on what how visible you want it.
I assume then my conclusion — that bluing the Action Menu icon (the “gear”) to indicate that a Note is attached is, in the specific case of Actions that have additional settings, and further in the general case of any Action, useless — is correct. I thought I might have missed something or had been seeing a behavior specific to my installation. Without a visual indicator that uniquely specifies that a Note is attached to an Action, Notes are of very limited practical use, imho. That’s why I suggested a different modification of the Action Menu icon be used to show that a Note is attached to an Action.
I don’t know what the “and further in the general case of any Action” is supposed to mean.
So don’t use them then. There are a variety of different ways to annotate a macro, from most to least visible:
Comments
Renamed actions
Renamed group actions
Colors
Notes
Use the one that is appropriate to your requirements.
If you want something that is “in your face”, use a Comment. If you want something subtler, rename an action. If you want, you can use color coding. And if you want something to just include some extra information, use a Note.
Notes are not designed to be the only usage case. Whether there is a more obvious note indicator or not would not change that, the information is hidden until you click.
People has suggested Tool Tips, but tool Tips do not work well with dynamic information because the system aggressively caches them and is not particularly good at knowing when to show or hide them, so to have some sort of “hover over note”, I would have to implement something more like Safari/Mail’s hover links, and show the note elsewhere - a lot of code and UI for minimal gain when there are already a bunch of other facilities for this.
Use the facility that is most appropriate to your needs.
I think he means: If the blue icon color is not only triggered by a set note, but also by other things, then the blue icon color is no longer a reliable (useful) indicator for the presence of a note.
At the bottom of the Comment action it says “this action is for documentation…”. My point has nothing to do with the content of this but rather the fact that actions already have a built-in way to display text at the bottom. It would be great if there were a way to edit this for each action. This feature would be similar to making a comment, but it would be more clear what action the annotation refers to. It would also be similar to changing the title of an action, except it could allow for multiple lines of text.
I want to make it easier for myself to annotate actions according to different things, such as “Todo”, “needs work”, or “takes a long time to run”. Or if I downloaded someone else’s macro and started making changes on it, I want to indicate which actions I if altered. All of this does not fit in a title, so it has to be in a comment. Sometimes it feels cluttered, however, to have comments in line with my functional actions since a comment does not perform any function on run.
Picking this up after 5 years because it's echoing the process I recently went through.
Debug Mode
I would like to add that renamed groups and actions also help document the steps performed when you are in Debug mode. Comments appear in Debug mode too, unless they are Disabled. I'm finding that disabling Comments (weird to disable something that does nothing, right?), especially to remove ToDo notes, etc., can make the Debug display flow smoother, or I can add an enabled comment specifically to indicate where I am when I'm running the Debugger.
Visibility of Notes
As a 40-year technical doc editor, I will add my vote first for some unique and visible indication that any particular action even has a Note attached, and second, more difficult to implement I'm sure, for that Note to be displayed as popup when hovering over the gear icon, or some other way being able to skim to it quickly rather than having to actually open the gear menu and select the menu item as a second mouse-aiming step.
.
.