Annotation UI Design

[kirlat]

This issue is to discuss the concept of the annotation UI. There are two types of UI changes that are needed for the annotation data:

1. Display of the annotation data that is already stored in the system.
2. UI for altering (adding, editing, or removing) the annotation data.

Existing annotation data would probably be displayed (1) within the current UI layouts, with some extensions to it (to show, for example, user comments). The (2) is more challenging, on my opinion, as it requires to display not only the data, but also the controls for editing it, which takes much more space. It is also important to to tie elements that will be edited with the specific controls.

On my opinion, much fewer users will use the editing UI (2) than users who would be viewing the annotation data (1). Because of this, and also because of the sometimes complex functionality required from the editing UI, it is important to make the editing UI as functional as possible, even if it will mean for it to be more verbose. The majority of users won't see this verbosity, but those who do would probably value its functionality.

If the existing annotation data will be displayed in the regular "viewing mode", I think that the editing of the annotation data would require a special mode to switch into (an annotation editing mode). When this mode is on, It would display the specific controls for editing annotations. It's better not to show those controls all the time because they will take too much space. It's better to show them on demand.

Here is the first take at how the annotation mode control might look like: The look is not final and might change in the future, I think it would make sense to concentrate on discussing the concept first.

An annotation mode icon is small and unobtrusive, and we can place such icons to various parts of the UI (the popup, the panel, etc.).

The annotation mode, when on, should change the look of the app in a way that would be easily noticed, I think. That will be an indication that the user is in a special editing mode that is different from the regular viewing mode. User would probably not stay in the annotation mode for a long time: he or she will switch to it, edit a piece of information, and switch back to the "viewing" mode.

Here is how I think the first iteration of the "annotation" editing mode might look like (colors and styles are subject to change):

The elements inside the square brackets ([]) are buttons to perform specific editing actions. The light blue background connects the controls to the element that they alter. I think we could associate a specific color with each editing mode; we might have several in the future: one for annotations and others for something else. The presence of elements with the light blue background would be an indication to the user that the annotation editing mode is on, that the UI is in this specific mode and that the annotation data can be changed (which he or she should be careful with).

The "Annotation mode is on" near the annotation mode control also serves as a reminder about the specific mode the user is in.

The editing controls in the square brackets are text, not icons, because icons from the current set we're using (Font Awesome) are generic and can't, on my opinion, adequately reflect specifics of annotation data editing tasks. I think having text makes controls much more informative.

There is a color associated with each specific action: green with adding the data (adding a lemma in the example), blue with editing the data, and red with removing the data. I've also added symbols (+, *, and -) associated with each specific action (we could use icons here too but I think letter symbols are combined with test better). I think the symbols along with the text will provide the better visual clues than just text notes. We could also use potentially use symbols alone to represent actions in a more compact UI, if we'll need to.

We could also add tooltips to the editing controls to explain them better.

@balmas, please let me know what do you think about the concept and whether it is the right way to go for us. Thanks!

[kirlat]

Some notes from the Slack discussion of the design (@balmas,please correct me lest I forget or misinterpreted anything):

• There could be multiple annotatable elements. It might happen that every element in a container might be annotatable.
• We should try to create a UI as simple as possible, with annotatable elements being designated visually. In more complex cases, however, we might instead of single elements highlight editable element groups. Once selected, such group will expand itself and show editable individual elements within the group.
• Annotation UI should work on both mobile and desktop.
• It might make sense to use data attributes to mark those elements that are annotatable. CSS rules to highlight them will be applied according to values of those attributes.

[kirlat]

Underwent through several iterations, here is the annotations UI layout that I like most at the moment. I am not saying "design" because the purpose is to show the design principles, not the final design of the elements. The final design would probably be different in terms of colors, shapes, etc.

I've tried to keep the layout as simple as possible: it will be, I believe, more understandable for users. It will also allow us to create more universal UI elements for editing the annotations. I've decided to mark each element that can be annotated with a thin blue frame. Because the frame is thin and the color is subtle, it make it bearable, on my opinion, to have every element highlighted. That makes things simpler for users: a user can click on the element and go directly to editing it, without opening the element group first. We can use groups where situations are more complex, but I think it's better to avoid them whenever possible, because they will make UI more complex, on my opinion.

On the layout above a situation is modeled when the user selected a part of speech of a lemma to add or edit a comment. The selected word is marked with the blue background: The selected word, once clicked over, will be deselected. So the click (or a tap, on mobile), toggles the state of selection. I think this principle can be used for both annotatable elements and for the editing actions.

As a result of a word selection, an annotation action panel is shown below the part of speech: It lists all the possible actions for the selected element. Those actions would be different for different classes of elements. That will define what buttons will be shown within the action panel.

In the example the "Comment" action is selected within the action panel. As a result, a comment form is displayed below the action panel: It has two buttons to either confirm the editing or cancel it. The same form can be used for adding the comment: if the comment does not exist, it will be added If it does exist, it will be edited. We might also have actions to confirm or negate the comment, if that'll be needed.

I think these examples illustrate the principles of the UI. I think that it is simple yet pretty flexible. It works well on both mobile and desktop.

Please let me know what do you think. Are there any more complex editing cases that are not shown here? I will try to create layout for them then.

[balmas]

I think the concept is good. I've marked up the screenshot with some comments:

[kirlat]

Thanks for your feedback!

Yes, this is for removal of the comment, but I'm still not sure how it's better to handle it: the alternative might be to use the "edit comment" button ([*Comment]) for adding, editing, and removing the comment text. There is also the question of how to deal with multiple comments from different users. But I think we can figure it out in the process. I feel the most important thing right now is to settle with the concept of annotation components and only then decide what exactly would be within each component.

The dialog for removal of comment might looks like below:

   

Would providing a selection for the whole line be adequate?

   

For inflections, we could probably show editable elements grouped together:

Would that work?

When there is a limited amount of actions available for the element, we can show them at the right side of the element:

This is how the whole popup might look like:

I think the general principles should be:

• Editable elements and panels with editing actions should look similar (because they belong to the same annotation mode), but editing actions panel should be more prominent to be more noticeable than the selectable elements. Right now action panels have thicker borders and light background while the borders of selectable elements is thinner and there is no background there at all.
• Both editable elements and the actions could have the regular and the selected state. The selected state is currently designated with a darker background. The states are switched with a mouse click, or a finger tap.
• There are also editing forms. The purpose of the form is to get the user changeset and send it to the business logic that handles it. Forms should have minimal logic of their own.
• Each component (editable element, actions panels, and editing forms) should be independend of each other. They should not be aware of each other's existence, ideally. When annotation mode is on, the annotation business logic should review the container, identify editable elements, and insert action panels and forms whenever appropriate. It should also popuplate data attributes and other data that may be necessary for editing actions and forms to work. This should make the architecture flexible: we would be able to add new or to change existing elements with minimal changes to the other elements.

What do you think about the approach above?

[balmas]

Each component (editable element, actions panels, and editing forms) should be independend of each other. They should not be aware of each other's existence, ideally. When annotation mode is on, the annotation business logic should review the container, identify editable elements, and insert action panels and forms whenever appropriate. It should also popuplate data attributes and other data that may be necessary for editing actions and forms to work. This should make the architecture flexible: we would be able to add new or to change existing elements with minimal changes to the other elements.

I agree with all of this.

[balmas]

Editable elements and panels with editing actions should look similar (because they belong to the same annotation mode), but editing actions panel should be more prominent to be more noticeable than the selectable elements. Right now action panels have thicker borders and light background while the borders of selectable elements is thinner and there is no background there at all. Both editable elements and the actions could have the regular and the selected state. The selected state is currently designated with a darker background. The states are switched with a mouse click, or a finger tap. There are also editing forms. The purpose of the form is to get the user changeset and send it to the business logic that handles it. Forms should have minimal logic of their own.

This sounds like a good place to start. I think we'll have to get user feedback and see how things look in practice before we can commit to a specific design though. And I'd like the code to be flexible so that we can easily apply different styles without affecting functionality.

[balmas]

Yes, this is for removal of the comment, but I'm still not sure how it's better to handle it: the alternative might be to use the "edit comment" button ([*Comment]) for adding, editing, and removing the comment text. There is also the question of how to deal with multiple comments from different users. But I think we can figure it out in the process. I feel the most important thing right now is to settle with the concept of annotation components and only then decide what exactly would be within each component.

Agreed. I think we also still need to work through what the UI for actually displaying the annotations will be. Some things to think about with that include:

• a user will be able only be able to edit their own annotations
• a user will be able to see (as well as hide) and comment on annotations made by others

[balmas]

Would providing a selection for the whole line be adequate?

In this case of the short definition, yes.

[balmas]

For inflections, we could probably show editable elements grouped together:

Would that work?

Possibly. I think what we would probably need to do is support editing at each groupable level. So, in this example. the user might say the form is NOT singular, in which case everything grouped under singular is invalid, or they might say one group under singular (e.g. gen. m.) is invalid, etc.

[balmas]

@kirlat I think we're getting close to something we could open up to a wider audience for feedback. Could you make screenshots with the few changes requested above AND in those remove the Login prompt, which is distracting (and the text of which will be changing since login will now also be required for annotation). Thanks!

[kirlat]

Possibly. I think what we would probably need to do is support editing at each groupable level. So, in this example. the user might say the form is NOT singular, in which case everything grouped under singular is invalid, or they might say one group under singular (e.g. gen. m.) is invalid, etc.

I think we could probably handle it by shown both the group and its individual elements as selectable objects:

We could also use a more compact variant of the above:

I don't know a functionality of which one would be more easy to understand.

[balmas]

Possibly. I think what we would probably need to do is support editing at each groupable level. So, in this example. the user might say the form is NOT singular, in which case everything grouped under singular is invalid, or they might say one group under singular (e.g. gen. m.) is invalid, etc.

I think we could probably handle it by shown both the group and its individual elements as selectable objects:

We could also use a more compact variant of the above:

I don't know a functionality of which one would be more easy to understand.

I think this could work.

[kirlat]

Here is a screenshot of the version with all changes included:

The code that generates this mockup is available in the dev-annotation-ui branch.

Please let me know if any other screenshots need to be rendered.

[balmas]

@kirlat please create mockups for the following use cases

---

Reference: alpheios-project/morphsvc#29 (as described in https://github.com/alpheios-project/documentation/issues/40#issuecomment-713186268) Summary: add vocative case as a possible inflection of the Latin word senatu (lemma senatus)

The popup should be the results of looking up the Latin word "senatu", with the user having selected to add an inflection to the form "senat-u" of the lemma senatus.

I think we should have a [+Inflection] below the existing "sing. dat. abl." inflection group

Clicking on that should open the Action Panel which should have selection dropdowns for Number, Case, Gender, with Gender pre-selected as 'masculine'. There should be 'Add' and 'Cancel' buttons.

---

Reference: alpheios-project/morpheus#16 Summary: add short def for Greek word "καταλείπω"

The popup should be the results of looking up the Greek word "καταλείπω", with the user having selected to add a short definition for the lemma "καταλιμπάνω", via a [+Definition] button that should be below or next-to the current short definition of "= καταλείπω, Thuc.".

Clicking on that should open the Action Panel which should have text input boxes for definition and source, with 'Add' and 'Cancel' buttons.

Let me know if any of this isn't clear. I need to mockups for our advisory board meeting on Dec 2. Thanks!

[kirlat]

Reference: alpheios-project/morphsvc#29 (as described in #40 (comment)) Summary: add vocative case as a possible inflection of the Latin word senatu (lemma senatus)

Would something like below be workable for the scenario described above?

[balmas]

yes I think so. thanks.

[kirlat]

Here is how it might look, I think, for the second case.

Do I need to provide any full popup screenshots for both of those cases?

[balmas]

That looks good. If it's not too hard to do, yes full screenshots would be helpful. Thanks

[kirlat]

Here are the screenshots.

The first case:

The second case:

Please let me know if they require any corrections.

[balmas]

I just have a question - why are the lemma and form buttons highlighted with the light blue background in these examples?

[kirlat]

I just have a question - why are the lemma and form buttons highlighted with the light blue background in these examples?

Is your question about the element shown below?

I think we need to have two kinds of elements: the annotatables (the ones being annotated) and the annotation controls (the buttons and the forms that are used to alter the annotations). Each must have two states: the regular and the selected.

So the annotatable elements in the regular state are like below and in the selected state are

For annotation controls the regular state is and the selected state is (the [+definition] button is selected in the example).

Does this make sense?

After your question I've realized that it's probably confusing that the selected annotatable element and the annotation control element in the non-selected state have the same color. Probably we should change one or the other so they would look different.

What do you think?

[balmas]

ah, ok I see now. I agree we need different colors for these.

[kirlat]

Here is an adjusted version. Please note that colors could be a subject to change. The selected annotatable element is lavender, the selected edit action button is light yellow:

[balmas]

I think that's fine for now, but would it be possible to get rid of the bluish background behind the lemma and form buttons?

[kirlat]

Here are the adjusted versions:

[balmas]

excellent. thank you!