[Admin note: forgive me, I’ve broken this into a fresh thread as I think it warrants some more input from the general community]
It took me a long time to realise this. Perhaps it is something that could be made more prominent in the documentation.
Sure, but where?
I think there are two inter-acting assumptions that it assumes (incorrectly) that all users will make.
- All attributes exist for all notes. Once an attribute is defined in the document, it is available to ant note (agent, etc.). Other possible analogies? From a database perspective, all records (notes) have all fields (attributes) defined. Rollodex: each card (note) has all boxes (attributes), even if not used. spreadsheet: each row (note) has every column (attribute) even if the cell for a given column isn’t used.
- Building on the above: key attributes are simply the subset of a note’s attributes (300+ system, plus any user created ones) that have been chosen to be displayed in that note’s text pane. More explicitly, the reverse is true, just because an attribute is not shown as a Key Attribute that does not mean it can’t be read or set via other means (Get Info, Inspector, action code, etc.).
- A note’s Key Attributes are in fact stored as an attribute in the note ‘KeyAttributes’. This is how notes can, for instance, inherit Key Attributes via a prototype.
Is there more that needs saying? Do we need more opening metaphors, given that our users are a broad church in terms of degree of familiarity with tech?
Once we know what to explain I think Tinderbox Help (‘Attributes’ for point #1, ‘KeyAttributes’ for #2 and #3) and aTbRef (perhaps a new article, in Objects & Concepts, under ‘Attributes’ on ‘What is a Key Attribute?’.
Other resources to consider would be the app’s two tutorials (app Help menu). In the “Getting Started” PDF, pp32–33, I think—again given the above—it is possible to miss the point that acting on an attribute does not require it to be a Key Attribute. In part, this is because the tutorial is, at this point, addressing another important early learning point about extracting metadata otherwise buried in $Text into attributes and in doing so introducing attributes. Perhaps it would be better if that lesson used the Inspector or Get Info first before showing how Key Attributes are a convenient way to see/set the values of contextually important attributes.
I think the point about Key Attributes being an affordance for convenience is also worth re-stating in the ‘Actions and Dashboards’ tutorial in Chapter 2.
The more recent ability to create new (user) attributes via the Key Attributes configurator whilst editing a note’s Key Attributes adds scope for confusion which hasn’t been addressed well as, for the seasoned user the purpose is likely already clear. Certainly, until reviewing it just now, I’d overlooked the main tutorial PDF’s scope to confuse a new user about Key Attributes.
So, before actually writing any new documentation, are there any other aspects of this that aren’t clear enough to someone starting out?
Could you clarify what “this” is when you write “It took me a long time to realize this”? There are about 4 features in the quoted paragraph so it’s hard for me to guess which of them was the “aha” moment for you.
Basically the first two sentences. Perhaps it is clearer if you read the paragraph in its original context (as a footnote to a longer piece). Anyway, what I take to be the main point of the paragraph.
Thanks for the non-specific clarification. 
So what you seem to be saying is that you were unaware that “key” means that they are displayed at the top of a note.
Nooo! That’s certainly not what I meant. Indeed, that’s very much the quite the opposite.
Further to @MartinBoycott-Brown’s last, the original context being referred to was my post here. I split this out into a separate thread as I do detect a sense (often implied not stated) that for many if it’s not a Key Attribute, the attribute doesn’t exist. If you are taking cues only from what is on screen and have no tech background, I can see how that incorrect assumption. The method of adding attributes we want to work on as Key Attributes in the ‘Getting Started’ tutorial feeds into this. IOW it has to ‘be visible’ or you can’t do anything with it.
1 Like
For the sake of clarity, it may be worth pointing out that although the full suite of attributes is available for each item (be it a note or whatever), they won’t be added to the underlying data (ie the xml record) for that item if they aren’t put there by either the app or the user. That is, of course, if I have that bit correct!
I took it to mean “I realised that I don’t have to make an attribute Key to be able to see it/use it”
This (from @MartinBoycott-Brown, via a side conversation) is useful to note:
The names you give things are important, and I think that “key” attributes is a problematic name. I don’t know what else you might call it, but to me it certainly did not communicate the idea of “attributes-that-you-might-want-to-see-above-your-note-for-some-reason”. To me it communicated “attributes-that-you-must-have-or-it-won’t-work”. In common parlance the word “key” has come to mean something like “crucial”, which does not help here. So for a while I worked on the mistaken assumption that the only attributes my notes had were the “key”, or “crucial”, attributes.
Amen. My suspicion is that, 20 years into the life of the app, renaming Key Attributes may be a challenge, but I do think an intuited assumption of them being “attributes-that-you-must-have-or-it-won’t-work” is a misconception upon which to work.
If ‘Key attributes’ is a confusing term, I wonder what better term there is for the the user-defined set of attributes optionally shown at the top of a note’s text pane?
2 Likes
No one who does not know TBX already, should read this. I am lost and have been for many years. Somehow, I think I will become clear in the near future. Or at least clearer.
I think you are referring to the list of Words that opens when you click on the lower right hand side of any note. You find a popup list there of something like user prototypes. Maybe the vocabulary is wrong but they seem like user defined prototypes.
It seems that Attributes can be used to find notes just as colors, shapes and other appearances of notes are used. This finding requires setting up of an agent. An agent could be set up to “collect” specific attributes. (What makes an attribute “Key” is unclear. In the example by MartinBoycott-Brown, the Keynote attributes appeared to be the main ideas of his writing.) The “action and dashboard tutorial” is about pre-defined attributes, but the same could be applied to user defined attributes, maybe?
I could also decide that some shape or color meant some category that is important to me. I would make a note labeling the important category and place it among the other agents? If it is at the root level, it does not need to be inside a note. Every child of that note will also have the same attribute. (Also, if the parent note was red, the child note will be red. So, I will be able to find subcategories of that note.) When I make notes, either I make a link or an alias or just remember that x color means y category to copy this info in my note? Since all this information is inherent in the way notes appear ect., this will all remain clear after I have forgotten what I am doing. So, somehow I will be able to find even a subcategory in a pile of slightly disorganized notes.
I fear you may have misunderstood the purpose of this thread, which is to discuss how/why users may be confused as to the purpose and meaning Key Attributes rather than getting help with using Key Attributes.
As to the processes you describe, there are a number of errors or wrong assumptions, which I will try to explain for you.
This does not relate to to Key Attributes at all. You are referring to the map view note pop-up menu for setting prototypes. It doesn’t show the built-in prototypes but rather all prototypes defined for the current document, built-in or user defined.
No quite. Querying the values of attribute(s) can be used to find notes.
No it can’t. In fact, it ‘collects’ aliases of note(s) that match the query (see my last paragraph above).
No, a Key Attribute is one that appears in any given note’s Key Attributes table. The discussion is about how users misconstrue the role/purpose of the table, in part due to the use of the word ‘Key’.
The “Actions and Dashboard” tutorial in the Tinderbox Help menu actually does involve use of both built-in attributes (e.g. StartDate) and user_ defined one (e.g. Dollars and Method). so I’m a bit confused.
No, as explained above, agents hold aliases. You can’t put a note into an agent. If you mean placing a note next to an agent on a map, this has no significance at all beyond knowing that you the user placed it there.
Rather, if it is at root level, it can not be inside a note. That is rather the point of the root—it is the ‘highest’ outline level there is in the document.
Not unless you use an agent action or set an OnAdd action.
2 Likes