Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Ask for the end-to-end user experience in explainers. #66

Merged
merged 3 commits into from
Jan 29, 2025
Merged

Ask for the end-to-end user experience in explainers. #66

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bc2f913
Ask for the end-to-end user experience in explainers.
jyasskin Jan 24, 2025
5c99a55
Update explainers/index.md
torgo Jan 29, 2025
0793fcc
Update explainers/index.md
torgo Jan 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions explainers/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,10 @@ you should always try to keep your explainer as brief and easy to read as possib

### Explain the End-User's need

Start with a clear explanation of the end-user problem you're trying to solve,
Start with a clear description of the end-user problem you're trying to solve,
even if the connection is complex or
you discovered the problem by talking to web developers who emphasized their own needs.
Use screenshots, mockups, wireframes, diagrams, and/or other visuals when possible, [with alt text](#alt-text).

Sometimes the connection to the end-user need is complicated.
Do explain the connection,
Expand Down Expand Up @@ -97,12 +98,14 @@ This is a time investment but will save time and energy for your readers.

### Describe Your Proposal Clearly

Wherever possible, use code examples rather than prose to “show” rather than “tell” your design.
Show how your proposal changes the end-to-end user experience
using screenshots, diagrams, and code examples.
Connect these into a narrative of what steps users currently follow,
and how your proposal improves that.

Use diagrams to aid understanding.
A picture is, for most readers, much easier to process than a slab of text.

Always provide text alternatives for readers who may not be able to see images.
A picture is, for most readers, much easier to process than a slab of text,
but always provide text alternatives for readers who may not be able to see images.
{:#alt-text}

- Simpler images may be described via an [image alt](https://webaim.org/techniques/alttext/#complex).
- More complex images may require a longer description in the form of a footnote or appendix to the document, linked immediately after the image, with a back-link to return to the section containing the image.
Expand Down