[Content Author Module 2: Structure] [low] Avoid metaphors

[iadawn]

In the Headings topic is it worth mentioning something about avoiding metaphors?

[daniel-montalvo]

Hey @iadawn

Thanks for this feedback.

I am not sure where this would be getting at.

If it relates to Making Content Usable for People with Cognitive and Learning Disabilities -- Amy Scenario 3: Designs that Make Use of Abstract Imagery and Metaphors, why would this only apply to headings?

Would you give me an example of what you would expect here?

[iadawn]

Metaphors in headings are more problematic because they serve to introduce the section. But if the metaphor is not understood then the value of the heading as that introduction is significantly reduced. It's not that it only applies to headings but that, as signposts, headings have more going on than just the text.

Perhaps an option would be to change:

write descriptive and meaningful heading text based on the heading purpose

to something like:

write descriptive and meaningful heading text, avoiding metaphor and abstraction, based on the heading purpose or following text content

[daniel-montalvo]

Thanks @iadawn

I am a bit uncomfortable with "avoid metaphors". I think it can potentially lead to contradictory/wrong advice.

What if the heading needs to be a metaphor itself, for example when you need to explain its meaning in a poetry review? Then you would probably need to put that metaphor in the heading to explain it in the content, so it would not be a good advice to avoid it!

A bit of an edge case, but still something plausible.

We could use another adjective to communicate that you should avoid abstraction/metaphors, like "concrete", "precise", or similar. Or what I'd prefer, "easy to understand", which would be a nice cross-reference to the first module.

The commit above changes it to:

write descriptive and easy to understand heading text based on the heading purpose or the following text content

[iadawn]

I am happy with the rewrite for the purposes of publication. I feel there is something still there though. For example, could use something like:

refrain from using non-literal heading text

'Refrain' is a nice word as it isn't as absolute as 'avoid' or 'don't'! :)

[daniel-montalvo]

Thanks @iadawn

Will mark then as "future iteration".

[daniel-montalvo]

I like "liberally" because it points students to what they have to do instead of what they don't have to do.

Could be:

write clear and meaningful heading text that literally describes the purpose of the section content