Comments, Notes and Tags

Over the past decade, we’ve evolved a number of overlapping / redundant concepts, all of which are related to a central concept, which I’ll call a highlight, which roughly corresponds to what the W3C Annotation Data Model calls a segment (link).

In particular, I’m trying to figure out how to communicate the difference between two different modalities for references to distinguish between when they have been have been created as elements within a resource (e.g. by an author) and annotations which have been created on top of a resource (e.g. by a reader / reviewer).

Currently, my plan is to differentiate these via their “action verbs” (insert and tag) so that users can “Insert References” into resources they can edit, but must “Tag References” on top of resources that they cannot edit (e.g. resources that have been integrated from a third-party source system a la Wikipedia).

As an additional complication, references within a document can be rendered in three ways: as an inline data object, as a hyperlink anchored on a highlight of text or as a preview showing a “card” of the data being embedded - examples below:

There are a number of other related concepts involved, but I’m most interested in advice about whether having ‘adjective-adjusted’ concepts is a best practice, or whether there’s a better way to express the distinction between a tagged “highlight” and an embedded “element.” I’ve attached a preliminary concept map below, with user-facing concepts highlighted in blue.

I’m always wary of terms which have a very strong common use and tag is already massively overloaded both as verb and noun, attaching one of a set of small labels. These are usually single words or, in the common hashTag style conjoined into a single word.

I do appreciate the distinction you’re making but don’t think the action verb is the way to go.

What about considering them from the timeline aspect - as original vs added chunks?

I generally agree with you, but there are a couple reasons why I think we may keep the term tag:

  1. Tags are actually a very old and deep part of the product that have been around since ~2005, and so users are already familiar with the Tagging workflow + terminology.
  2. The behavior of “Tagging” is actually isomorphic to tagging a photo in a social media app - it creates a linkage between an object and a section of a document / image / video / audio clip.

As a result, we use a label concept to represent the small labels, and the tag concept to represent the process of creating references and notes on top of read-only resources within the system - note that I imagine eventually merging the label and **tag concepts so that users will be able to treat their taxonomy of labels as an ontology of tagged objects.

The reason I don’t like the timeline perspective is that the use-case is for adding functionality to collaborative UIs, and so it’s not true that tagged references will always be added after the inserted references.

Hi Peter, and welcome to the forum!

It seems that you have a few different things going on here:

  1. You have a concept of Reference, which is a special kind of object with special behavior distinct from plain text.
  2. You have a concept of Tag, which involves someone (usually distinct from the author of a document) annotating a document with something. That something may be a reference, but it could also just be a comment. If this is right, then I would define Tag polymorphically so that its content-type is a parameter, and is independent of the concept itself. And given the behavior associated with this concept, might Annotation not be a better name?
  3. Your tags can be attached to the structural elements of the document: for example, you can presumably attach a tag to a paragraph. But a tag can also range over the document in a way that cross cuts the structure, by having start and end points in the middle of different elements. I’d be tempted initially to consider whether this might be a concept of its own (say, Segment, using the W3C term) that has independent uses unrelated to annotation. For example, might there be a Highlight concept in which a user just applies a color to a range of text, like a physical highlighting pen?

I am wondering if we are falling into an (usually-reductive) taxonomic problem here. This has me thinking about a similar problem that can arise in pattern languages, as in how design patterns can befall this condition.

Perhaps the challenge is contextual rather than a matter of taxonomic rigidity. In particular, there needs to be a way to address intentionality (i.e., an artifactual fragment viewed as an annotation and hence authored by different parties) without investing intention as intrinsic to the artifact.

Having offered that concern, I also think the discussion of perspectives around certain entities is worthwhile, as we see it employed in this discussion too. I think I would modify @dnj’s use of type of a tag to be about expression of a tag, unless that is a new can of worms.

This is surfacing, for me, a challenge that lurks in pattern languages and I see that there is homework I need to invest before I drive off into the weeds. It comes back to the ways that digital computers exhibit a form of linguistical behavior that is inherent in the stored-program concept and that we can get tripped up over in dealing with computational artifacts.

@dnj - broadly agreed; unfortunately, because of our Graph and Map applications, we’ve already used the word annotation to represent a primary element that a user creates within the Graph or Map resource / file (e.g. a text box, line, box, circle). I generally like your breakdown into three distinct concepts: References, Tags and Highlights, but my main question is around “conceptual composition” - do I need N new concepts if I’m “composing” two concepts together?

Concretely, in my DAG, I’ve added a fourth concept (the Tagged Reference) that depends on both Tag and Reference but would love your advice on that. Because Notes can also be tagged, I also have a Tagged Note - this creates a lot of extra concepts which really just represent the conjunction of two concepts that already exist.

I think that @orcmid’s (somewhat baroque) response is pushing at this - basically, how do we model “conceptual adjectives” or “conceptual conjunctions” where the same “concept” needs to be be used in different contexts, with slightly different affordances based on the origination without resulting in an explosion of concepts?

First, a general observation about what we’re trying to do here. For me, this is about design, not philosophy. In the service of getting good design, we have to get our methods straight, and that might involve resolving some philosophical confusions. But our aim is to make software that is easy for its users to understand, easy for its implementers to build, flexible and maintainable, etc. Or at least as easy as possible given the complexity of the demands.

So, in this view, our question becomes: what are the right concepts for explaining this functionality and for implementing it in a modular way?

Regarding terminology of Annotation vs Tag, I would agree with @andydentperth that the term “tag” is already so widely used to mean a small string that is added to attract the attention of others that I would prefer to reserve the word for that concept, as it appears in Facebook. It’s for that reason that I used instead the name “label” for the different concept in which a user adds short strings to objects in order for finding and filtering them, just as the name is used in Gmail, even though in Apple Mail such labels are called “tags”. To me, the concept of annotation is so well understood in terms of the behavioral protocol (someone creates an artifact, someone else attaches notes to pieces of it) that I would continue to use that term for the concept, even if the name clashes with the schema in your applications.

In terms of creating a multitude of concepts: we definitely want to avoid that. Going with your preferred terminology of tag rather than annotation, if a note can be tagged, I would not create a new concept called “tagged note.” There’s no need for this. Your tag concept is polymorphic, and can be applied to notes, references or whatever. In just the same way, if you were explaining the concept of Comment to a user of StackExchange, you would explain the concept generically, and then perhaps point out that you can comment on both questions and answers, but you wouldn’t present comments on questions and comments on answers as distinct concepts.

Re: your final question: what are the “slightly different affordances” of different instantiations of the same polymorphic concept? To the extent that there are such differences, concept design suggests they should be eliminated, and if they can’t be eliminated, it’s possible that they represent truly different concepts and that a single concept is being overloaded.

This all makes sense:

  • Agree with the distinction between label and tag
  • Agree that the annotation concept is correct, even if we choose not to expose it because of name collisions within our specific application.

I think the problem I’m having is specifically with drawing the dependency diagram - basically, because there are multiple types of tags (polymorphism), a user can understand tags if they understand either note or reference, but the DAG implies that they need to understand both.

graphviz (4)

Do you have any suggestions for drawing the DAG?

A highlight is the thing you tag, but a note or reference is the thing you put inside a tag, right? If so, I would have tag depend on highlight, to show that, in the family of possible apps represented by the diagram, you can’t have an app that has the tag concept but doesn’t have the highlight concept. The dependences on note and reference don’t seem necessary, since you can have tags without either.

Is selector a concept in its own right, or is it just part of the mechanism of the highlight concept?

A selector is part of the mechanism of the highlight concept, so I’ve removed it. In our system, you can’t have a tag without either a note or a reference - that’s just a highlight, which serves the purpose of addressing a defined subregion of a given resource. Perhaps the right solution is to use the dotted line annotation that you used in the book - that actually looks fairly clean:

It extends nicely to the idea of notes / references that are inserted directly into a resource but remain anchored on a highlight as well:

I feel pretty good about this - will post a follow-up video once we get this all built out in the next 1-2 months, but really appreciate the guidance and help! Excited to continue these discussions in this forum and work to figure out what the right way to document / evolve a concept map like this over time might be.

Yes, using secondary dependences (the dotted arrows) may make sense here. Excited to see how this works out. Most interestingly: does this analysis suggest any new design possibilities to you?

Yes, I think so:

  • The rendering of all highlights needs to be somewhat shared, and I think having clarity around the different types of highlights in the system is going to help with a shared physical design language while maintaining the distinction between different types.
  • Tags need to be indexed in search differently than embedded notes and references, but should likely call into shared modules for the individual concepts as part of constructing the indexable structures.
  • A user needs to be able to identify all of their annotations (which should include tags, clips, comments) but embedded notes / references should not show up in that view.
  • The UI for creating tags should be identical to the UIs for creating references and notes - should be able to share some code + interactions there.
    ** All of these highlights should be addressable, likely with some combination of URL params + strong IDs.
  • Users should not be able to turn off the rendering of embedded references, but must be able to toggle on and off the rendering of annotations - pretty big distinction in the UI for the two types of notes and references.
  • Should be able to embed consistent UIs for highlights within the views of each of the other concepts so that users can gain context without having to open the annotated resource.

Not sure if these were the kind of design possibilities that you were thinking of.

I can’t claim to understand all of these, because I don’t understand your app fully, but several stand out for me:

  • Making highlights addressable and representing them consistently in different contexts: this seems to be about making highlight a full concept in its own right.
  • Using the same UI for tags and refs and notes: this seems to be about exploiting the polymorphism of the tag concept, so that the contents of a tag are edited in a way that is independent of them being inside a tag.

PS. Your comment about annotations makes me think I misunderstood your earlier explanation: it seems that all annotations are indeed additional content distinct from the original document, whether tags or not? And a tag is a kind of annotation that connects a highlight in a document to an object (another document?) that already exists?

Yeah, language is confusing - perhaps there’s a good way to annotate concepts with local and global or something to help with namespacing. We have a local annotation concept (annotation_local) which is used to allow authors to annotate arbitrary 2D resources (e.g. maps, graphs, charts). This is distinct from the annotation concept (annotation_global) which I think you’re using, and which is what the W3C Annotation Data model is describing. In other words, annotation_local is used to refer to elements which are contained within a given resource; annotation_global is used to refer to elements which refer to a segment of that resource.

A tag is a type of annotation_global that is created by a user which either a) creates a bidirectional link between the content that’s been highlighted and an existing data object (either a document or other semantic entity) or b) represents a note on top of the document being tagged.

The more I think about it Tag is really a “compound concept” - the combination of a highlight and either a note or a reference, which is why the polymorphic behavior will be useful for simplifying the design.

Thanks so much for your help - will be sure to come back with a demo video and see how it feels!