Design a way to convey five different types of textual annotation so that readers can understand model annotations of Jingdian Shiwen

[rlskoeser]

This issue tracks design work through the CDH design review workflow.

Here is a link to the

Description:
Review Nick's draft for figure 7:
https://jdsw-figures.glitch.me/annotations

Is highlighting the best solution here? How can we include a key or legend to make the types of annotations more clear? How do we make this information accessible?

How the proposal/idea can fail:

• color scheme with sufficient contrast for accessibility that also works with SW theme
• likely will need separate annotations for screen readers

Questions:

1. ...

Additional context
Potential overlap with #319

[gwijthoff]

@gissoo here's a quick sketch of the different elements in @thatbudakguy's draft for figure 7:

@thatbudakguy can you confirm that:

1. in the primary text from the Book of Changes, the Chinese text is a number of hexagrams formed via permutations of line-forms while the English text below that line is a description of how the hexagrams were formed?
2. the highlighted, color-coded elements of the Jingdian Shiwen (people, works, phonetic annotations, etc) were automatically identified using your machine learning model?

[thatbudakguy]

sorry, I feel like there's so much going on here...maybe some context will help. the primary text from the Book of Changes is describing how the sixty-four hexagrams that comprise the Book itself were originally "generated". here's what a hexagram looks like:

as you can see, it's formed from six horizontal lines, which are either solid ("strong") or broken ("weak"). there are 64 permutations of six such lines, so the text is basically saying "when you take a solid or broken line and repeat it six times, and get every unique version of that, you get the 64 hexagrams." they look like this:

when using the Book of Changes as an oracle, you construct a hexagram that is more or less your "fortune" for that moment. (incidentally, the Book figures prominently in PKD's The Man in the High Castle, and he actually used this method of fortune-telling to guide his writing process for that book).

[thatbudakguy]

the highlighted, color-coded elements of the Jingdian Shiwen (people, works, phonetic annotations, etc) were automatically identified using your machine learning model?

i think this particular example was created by hand, but i just checked and the model produces this same output, so yes.

[gissoo]

@rlskoeser @gwijthoff below are details of what I have done for figure 7. When viewing the links, please zoom out to scan the mobile versions too.

Here is the latest version, v3 on desktop and mobile.

Here is version 2 on desktop and mobile. – The only difference between 2.2 and 2.1 on desktop is the style of the legend.

• NOTE: on both of these proposals there are minor differences between mobile versions 3.2 and 3.1 as well as 2.2 and 2.1, I'm mainly trying to make it easier to scan the annotation types on mobile and make better use of vertical space considering the need for scrolling.

• Please let me know your thoughts. I've not tried the purple style for this figure, it won't be hard to do, I have been spending more time on the mobile version for this one.

• Question: Should we / how much do we incorporate the original/primary text portion in this figure for the hexagrams? I'm wondering how they can be incorporated to be understood better, because I can't see how much they depend on each other..? – if you have ideas please let me know.

[rlskoeser]

@gissoo I love this! The various underline symbols are so readable and clear and I think will be very accessible. Is your plan to export assets I can include as a repeating pattern under the designated terms?

I like the alternating gray and white in v3 but I prefer the legend separate as you have it on v2.2 instead of interspersed with the text. If you want to keep it interspersed with the text, maybe we could flip the order so the annotation label is after the translation?

For mobile I like v3.1 - I think it is more readable to keep the underlines consistent with desktop, and I think it will also be easier to implement. I guess it's harder to do a separate legend on mobile... and I'd rather be consistent between desktop and mobile.

I don't think it's worth the effort to use the purple style, I think that will detract - the white and gray with the different indicators looks really clean and readable to me.

[gwijthoff]

This is fantastic work, thanks @gissoo! I agree with @rlskoeser that the legend is probably better separate, as in v2.2.

For mobile, also in agreement preferring v3.1, though if possible, without the "phonetic" "people" tags etc., instead just using a vertically stacked legend like the one you designed in v2.1 desktop?

To answer your other question, I think it is important to Nick & Gian to include the original/primary text portion, which the Jingdian Shiwen passage you've underlined comments on.

[thatbudakguy]

Wow...these are so cool!! I'm blown away.

A few thoughts; I had different reactions from @gwijthoff and @rlskoeser but not sure if that matters here & I'm happy to go with whatever.

• I like v3.2 more than v3.1; the underlining doesn't seem as useful when the only thing on the line is the segment itself anyway. Also I don't think it's possible to do the wavy-style underlines as a traditional "underline" on desktop anyway, so we're probably going to need to do custom stuff no matter what (which I am fine with!)
• I think the alternating white/gray segments in v3 is a helpful contrast.
• I actually like the labels underneath the segments in v3 more than the legend in v2. It feels more natural to me to have each segment remind you what type it is (and honestly it might even make it so that we don't need the fancy underlines, or they don't need to be as fancy). Using the singular forms ("Person", "Work" instead of "People", "Works") would make it feel more natural to me.
• Breaking up the segments this way might mean that we don't need to include the english punctuation in our translation (like ";", ".", etc.) because we aren't displaying the translation as a full sentence. I like that! There's not really a concept of a "sentence" in ancient Chinese anyway, so having a bunch of separate segments feels more natural if we don't need to insert things like "," in between them.

[gissoo]

@rlskoeser @gwijthoff @thatbudakguy thank you for your feedback – below are my responses and thoughts:

• Yes, @rlskoeser I would export the patterns for you to implement
• I definitely prefer the grey and white versions as well since relying on the legend makes the reading flow harder , and I definitely would discourage us to use a legend on mobile, it's so much worse – @thatbudakguy I think the patterns are still useful even with the annotation labels because it makes it easier to scan and see how many of each annotation type exists in the text.
• I like Nick's point on the mobile v3.2 version, I agree and it was partially my rationale, but I don't feel strongly.

So I have revised the version 3 both on desktop and mobile so that based on Rebecca's suggestion the annotation labels come after the translation (with a bit more spacing), thank you, I think this is so much better! Here is the desktop version and here is mobile v3.3 and mobile v3.2

Please let me know what you think and if you feel strongly about anything written above.

Question: sorry trying to understand this better, so we are including the primary text like this in this viz?

[gwijthoff]

Authorial preference takes precedent! I approve all @thatbudakguy's suggestions above and like that he and @gissoo are in agreement about the direction for this mind-blowingly cool figure. So exciting to see, through this visualization, all of the many different ways that a text can contain information.

Question: sorry trying to understand this better, so we are including the primary text like this in this viz?

@thatbudakguy correct me if I'm wrong, but I believe the answer is yes

[thatbudakguy]

Question: sorry trying to understand this better, so we are including the primary text like this in this viz?

In my initial mockups I had included it, but for this figure specifically, @GDRom suggested removing it, because it's somewhat long and might distract readers from the focus, which is the text from the JDSW itself. I think I might agree — we really are only interested in the headword (相摩) which is that two-character part of the original text that is underlined.

[thatbudakguy]

@rlskoeser I've got an idea for how to do the vertical underlines (? does that even make any sense? sidelines?) and might take another pass at this this week.

[rlskoeser]

I vote for with excluding the initial explanatory text and focus on the relevant portion only.

I like it much better with annotation labels under the translation text. I'm ok with doing that instead of a legend on mobile (which would be hard to make work well anyway).

@thatbudakguy I think I'm losing track of versions but happy to go with the one you like - I take it you like the vertical bars on mobile rather than horizontal? I think this can be done with a border-image and Gissoo will provide the pattern images to use, so it's not difficult. (It's probably possible to do with pure css but not sure it's worth the effort, unless you want to take that on.)

Do we have any decisions left? Can we document what we've agreed on and make an implementation issue?

[rlskoeser]

@gissoo I think everyone has reviewed and commented and we're ready to move forward. Can you create an implementation issue for me and make it clear in Figma which version we're going with, and export/upload any assets that are needed? You can close this issue when that's done.

@gissoo Please flag if there is anything that is still not decided or unclear.

@thatbudakguy if you want to work on this or help implement, please LMK. I think the structure you've already got in the html will make it fairly easy to apply the new styles.

[gissoo]

@rlskoeser @thatbudakguy @gwijthoff thank you for your feedback! @thatbudakguy that makes sense to me now about the specific part of the primary text, how about this? https://www.figma.com/file/MEt3gfKX4N3WTLPbLGBbGC/Startwords?type=design&node-id=4857%3A3153&mode=design&t=HKTUdGdHqSU6K6oG-1 – I made it clear what part of the text you're annotating ...if not I can just go with the version I proposed originally without the primary text line. In the meantime I'll prep the final versions for hand off.

[gissoo]

@rlskoeser While I wait for Nick's response, here is the finalized version on desktop and on mobile. I will go ahead and create an implementation issue for this figure.

[thatbudakguy]

I do like the visual hint about what part of the primary text is being annotated (it's definitely clearer than the underline). However, I think if we included the primary text, we would also need to include its translation and its source info (like I did in the original draft of the figure). That adds a lot of stuff to the figure, which is why I think it might be too distracting. Let's keep the final version you have now.

[gissoo]

Thanks, @thatbudakguy. @rlskoeser I'll go ahead and close the issue. I have revised the underlines to almost match what Nick has done. Here is the desktop and here is the mobile – It might be better to make both the dashed line and the solid line's width to be 6px and the works annotation to be one thick line with a 12px width.