Consider: Moving the "Intent" sentence from "Additional Information" to the start of the specification section.

[susannah-hill]

The "intent" sentence in each specification's "Additional Information" area sets context and gives a rationale for why the specification has relevance. Would it be worth the effort to move the "Intent" to the start of each specification?

[codewordcreative]

GMTA. That's pretty close to something I proposed, too. The original idea I had was to make a shorter, snappier summary for the beginning, though. The problem is that - while it'd work automatically for many - a lot of the current intents aren't so snappy, so not as suitable as an intro. My thinking, given the workload, is that I would shift that to the next round of edits - after the current deadline. Though obviously if others want to contribute to that task, it's less of a challenge! The intents in general could be edited further imho, but it'd require a lot of discussion with each task force in each case.

So I guess I am saying... Yes, this would be ideal. But not necessarily right now, because the intent parts for many chapters just aren't snappy enough - even with some editing for readability - and could end up overwhelming somewhat.

I'm open to any ideas others have, though! If we could get all the task forces working to improve those so they are snappier and work as an intro, it would be cool. It would help readers see where things are going.

[airbr]

@AlexDawsonUK I took a quick attempt in the browser to show what a guideline could look like with this adjusted:

@codewordcreative Seems like a reasonable enough change to me but the only consideration I have is would a repeat reader need to read the intent everytime? Its ideal and optimized for first time viewers perhaps.

[codewordcreative]

Thanks, @airbr. The idea I had was to use snappier, shorter, mini intents. I think the full, longer ones could be too distracting. It should ideally serve as more of a reminder, not a full instruction. And possibly not directly an intent.

So for this one, something like:

Many variables can affect user experience and sustainability. Identify these to discover where you can make progress.

See what I mean?

And I think if we kept it short, then there are two other questions:

1. In some cases, we could even do away with the longer intent. As in, does the full intent really say anything my shorter version doesn't?
2. If short, perhaps there's no real issue for skim-readers and repeat visitors.

Incidentally, if people don't need the additional information, a version without that - or with that external - could also be worth considering.

However, I think there may be guideline-related reasons that we need to have a longer intent. I'm not sure. Just in terms of the reader, many of them are long-winded and repetitive, or pointless because that particular topic is self-explanatory.

[TzviyaSiegman]

I recommend holding off on this for now. I agree with @codewordcreative about making the wording briefer in this release. In WCAG, sections like this are relegated to a separate Understanding document. The reason we created "additional information" was to embed that info in the doc without it being a distraction. I do like the way that one short, snappy descriptor looks above the SCs (thanks @airbr for the demo), but we need to see if we can do that for everything. Perhaps we should also consider whether the word "intent" is best.

[mylonelycomputer]

I know this is a bit of a reach, but is there a resource you can refer me to to better comprehend/read technical spec documents? I know everyone is very busy on top of their jobs, but I'd like to be able to contribute and help in giving informed feedback. I guess the vocabulary, grammar, and jargon feel very foreign to me and although I know we try to make these specs as clear cut as possible to remove room for error/misunderstanding, I still feel awkward trying to work my way through them. :) Any help would be much appreciated!

[TzviyaSiegman]

@mylonelycomputer Message me on slack

[codewordcreative]

@TzviyaSiegman Yeah, that's exactly what I am getting at. I started it with the web dev section, but then I realised I would never realistically be finished in time if I did that - as I would also have to clear such a big change with each task force, for each statement.

What might make sense - and perhaps also resolve some simultaneous issues regarding scope of individual spec (see my proposal about keeping 404 pages lightweight)... How about this:

Chapter 1.1 Make Success Criteria clearer.
Success Criteria need to be clear for as broad an audience as possible. Summaries can help people find their way at a glance.

SC: Add one-line summaries to Guidelines to replace the current intent content.
....

... Then you have all the usual content.

And then:
Additional information:

Considerations/Please note/Common problems:

• The WSG is an official W3C spec. As such, it must itself meet certain criteria. This means it is sometimes not possible to translate every criterion into plain language.
• The educational materials can help some users to better understand the content.

(This is where you'd relocate any important notes that are currently weirdly included in the intent)

...Just as an example, playing around with the idea of this change itself! That could solve issues where there is a really common issue that may or may not belong explicitly in a guideline itself, but a well-placed reminder can provide clarity or generally help to further reduce carbon impact. For example, the adjustment relating to lightweight 404 pages - this would be a place to highlight the fact that 404 responses always include the full page. As these are often hit by crawlers - both benevolent ones and malicious ones looking for a loophole - there's a considerable impact to be had from avoiding unnecessary graphics on that page, for example. That may not completely fit in the Hosting section where it lives, but it could go into a note. It may also help to explain crosslinks. There is the side note that it may help to ensure the knowledge exchange in debates isn't fully lost. For example, in including this in relation to 404s, we could also emphasise the UX-related sustainability benefit of dynamic tools to help people find their way.

Just a thought! I never really did gel with the Intent sections. It felt like it was trying to explain something that was already clear enough in most cases, but not in language that would help people with less techy backgrounds to understand it. I think that's probably where @susannah-hill was coming from.