Formatting of common strings/structure in a11y design docs

[jessegreenberg]

Back around the a11y sprint, there were questions about how to format strings or structure in a11y design documents that are common to all sims. For instance

The second half is grayed, presumably because it is added automatically by our infrastructure. I think this is helpful, but I haven't seen a design doc in a while. @terracoda @emily-phet what are your thoughts about this?

[terracoda]

@jessegreenberg, what design doc is this? It seems this one with blue and grey text is likely a very old one - a kind of first go at it. This is not what was adopted at the a11y sprint.

A better example would be John Travoltage, Friction and Gravity Force Lab.

I actually made an example template: SIM NAME: A11y Design Main (Template)

But I haven't updated it since July.

[terracoda]

@jessegreenberg, from the previous link, I see this design doc is for Color Vision which is not a good example. When a11y work continues on that sim we would have to update the a11y design document.

[terracoda]

Please re-assign if you need more information. Or perhaps this issue can be closed?

[jessegreenberg]

Awesome, thanks @terracoda. It was an old screenshot from a design doc dated at the a11y sprint. Makes sense it is quite stale.

In the current template we have this:

H1: {{Sim Name}} or {{Screen Name, Sim Name}} Paragraph for single screen on single-screen sims {{Sim Name}} is an interactive sim. It changes as you play with it. It has a Play Area and a Control Area. [...]

Paragraph for a screen on a multi-screen sims (see also joist/doc/HomeScreen.md) The interactive {{Screen Name}} Screen changes as you play with it. It has a Play Area and a Control Area. [...]

This is added automatically by our infrastructure so devs don't need to add it and doesn't require design. The core a11y team knows this, but newcomers won't. Should this be styled differently to indicate or even omitted from the doc to avoid duplication? Or is it useful to have in all of our design docs?

[terracoda]

Great question @jessegreenberg, I thought the curly braces kind of indicated that, but if that isn't a strong enough indication, we could indicate with a clearer label and or some kind of formatted text.

Would this work?

At the a11y sprint it was very apparent that using too much color and weird formatting would not work for designers. Formatting was simplified for readability.

I am opened to suggestions.

Please note that the red text above is likely new content from my last update in July. I think it has been implemented so I can change it to black.

[terracoda]

@jessegreenberg we can discuss briefly at next weeks A11 Des & Dev meeting.

[jessegreenberg]

Discussed during 11/13/18 a11y meeting.

@zepumph wondered about adding a Key/Legend at the top of a document or referenced elsewhere. Perhaps the legend should be inside the document because we may not want to update old documents if our conventions change.

@terracoda said that it was helpful for the boilerplate documentation to appear in all documents because it provides context for the designer and allows them to see all of the common documentation.

We will proceed with the convention that we will italicize boilerplate documentation in the document to signify that this is added in all sims by infrastructure.

Closing.