Place examples after the introduction text

[ZoeBijl]

While in a conversation with @matatk they mentioned that they had never seen the examples in the document. This got us thinking that the position of the examples at the very end of the design pattern doesn’t make much sense; links to the examples are only visible after you read the entire text.

We concluded that it would be much better if the example section was right after the introduction text. As Matthew said during our conversation “that way people can follow along with the text while looking at a working example”.

I’m willing to make this change if everyone agrees with it. What do you two think @mcking65 and @jnurthen?

[mcking65]

Interesting conclusion and proposal.

Does this mean that people only read part way through a pattern and then skip to the next pattern? I wonder how far they read before deciding to ignore the rest. When people skim, don't the headings visually stand out? Examples has a heading like the other subsections so I am surprised that it does not capture attention. Does that mean that people will then not be aware of the states and properties subsection if it becomes the last one?

Examples is the shortest subsection of each pattern. So, placing it first does at least make it easier to see more headings at once.

There are other possible solutions. For instance, I wonder if respec supports collapsible sections.

Before spending time on this, we should have it as a meeting topic. And, if we do do something like this, because it would impact the entire design pattern section, it would be a good idea to coordinate a good time to do it so it doesn't create unnecessary merge headaches for outstanding feature branches.

[ZoeBijl]

The headings do stand out from the text. However, some sections are rather long and detailed (which are both good things). It does however mean that some people won’t read the entire thing.

To give an example of how I would go about making a widget before I got involved with the APG:

1. Build the thing based on my knowledge of HTML
2. Add missing interaction as I think it should work
3. Question how to make a certain part accessible
4. Look up information about this certain part
5. Ignore the rest of the section

I’m certainly not saying this is how all developers do it. This is just to give an example of how it could go. Another example could be someone with limited sight. Event hough the headings stand out, it’s quite easy to miss the examples as—like you said—the sections are quite short.

If nothing else this gives more exposure to the code examples, which I think is a good thing.

[a11ydoer]

I am kind of in agreement with @MichielBijl and @matatk about raising visibility for the coding example. Currently coding example is heading level 4 and it is easily buried by lots of text before the developers reach into the coding example. I also see concerns for administering this change but that is different internal managment issue. Anyway, I think it is good idea to talk about this at the meeting.

[mcking65]

Per discussion in meeting on May 1, the task force has agreed to reorder subsections so examples is the first subsection followed by keyboard interaction and then roles, states, and props. @MichielBijl and @mcking65 will coordinate work to minimize conflicts.

[ZoeBijl]

This was done in df26880