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?