Add explanatory text and improve headings in Sass API Reference

[EoinShaughnessy]

What

Add explanatory/introductory text under headings in Sass API Reference. Possibly also revise some headings to make them more meaningful to users.

Why

Because of how the Sass API Reference is generated, no explanatory text displays under its headings. This means we are not telling users what the different sections can help them do.

There may also be an impact on accessibility - using headings that do not appropriately describe their related content is a failure of WCAG 2.4.6: Headings and Labels.

For example, would anyone coming to this content for the first time necessarily know what we mean by 'Assets'/ 'Settings' here? 👇🏻 Or even what the 'Sass API reference section' is for, generally?

Who needs to know about this

Laurence, Eoin

Done when

• we understand how 'group descriptions' work in SassDoc
• create content to add to headings (or 'groups', as they seem to be called) in govuk-frontend*

*However, the bulk of this work will be in the govuk-frontend-docs repo.

[EoinShaughnessy]

@kellylee-gds I asked the Accessibility Team whether there needs to be content under headings. They said:

It’s not an accessibility fail, but it is a preference for some screen reader users.

Basically, if there’s no content between headings, some users are concerned there is something there that they can’t access

so spend a while trying to get their software to access the ‘thing’ between headings

but when there is no ‘thing’ and it just leads onto another heading, this could cause confusion and waste time

[stevenjmesser]

@colinrotherham Do you know if we'll can continue using SassDoc now that we've switched to Dart Sass? Trying to work out whether this might be resolved by using a different API reference generator or whether we still need to solve the issue.

[colinrotherham]

@stevenjmesser Yeah no blockers continuing to use it

They're after help maintaining the project though:

• Maintenance Status SassDoc/sassdoc#555

Locally we use a different SassDoc theme (see screenshot) but it's hidden when deployed to Heroku

• Redirect Sass docs in review app to Sass API reference in Frontend Docs govuk-frontend#1892
• Redirect Sass docs when running on Heroku govuk-frontend#2706

These docs render the same SassDoc data

Even if there's no way of adding explanatory/introductory content to the SassDoc data itself, I'm sure we could match up known sections (in the SassDoc data) with content maintained in this repository before it gets rendered

[colinrotherham]

Sounds like #116 is an improvement right away