Skip to content
Merged
Changes from all commits
Commits
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
65 changes: 63 additions & 2 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,13 @@ Do explain the connection,
even if this requires breaking the “be brief” rule.
For example, see the
[explainer for deprecating `document.domain`](https://github.com/mikewest/deprecating-document-domain/#a-problem),
although even that could perhaps use another sentence
explaining why security boundaries are important for users.
and see [[#boilerplate-user-benefit]] for text to
explain why security boundaries are important for users.

Some features are intended to help authors and
have no effect on end-users aside from websites being developed more easily.
If your feature doesn't cause any harm or benefit to users,
use [[#authoring-user-benefit|the boilerplate for ease of authoring]].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you mean to reference the subsection of the appendix or the entire thing? It seems like this should be the entire appendix.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I meant to reference the subsection, since I meant this paragraph to just be about features that are meant to make authoring easier. The other parts of the appendix explain why features meant for security, etc, actually do help users. But I'm also not tied to the current text or link if you still prefer something else.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lolaodelola endorsed the subsection link, so I'll merge. We can fix in another PR if necessary.


## Write Simply ## {#write-simply}

Expand Down Expand Up @@ -179,3 +184,59 @@ See this rendered at
path: template.md
highlight: markdown
</pre>

# Appendix B: Boilerplate Explanations of User Benefit # {#boilerplate-user-benefit}

Some classes of features are meant to
help authors achieve some kind of user benefit,
like security, accessibility, or performance,
more easily.
Explainers for these features should say why that general area helps users,
but explainer authors should
spend most of their time explaining why the feature improves the area.
This section provides some boilerplate for some common areas
so that authors don't need to rewrite it every time.

## Accessibility ## {#accessibility-user-benefit}

> This feature is meant to improve website accessibility,
> which ensures all users can browse the web,
> even if they need to interact with their computers
> differently from the majority.

## Ease of Authoring ## {#authoring-user-benefit}

End-users come before authors
in the [[design-principles#priority-of-constituencies|priority of constituencies]],
so when explaining features designed for authors,
you need to clearly establish that there's no negative effect on end-users.

For example, [[css-nesting inline|CSS nesting]] primarily makes it easier to write stylesheets,
and the potential reduction in file sizes wasn't measured as part of justifying the feature.
On the other hand,
a feature like [[privacy-preserving-attribution inline|Privacy-Preserving Attribution]]
isn't in this category because it does have some negative effect on end-users
(via bandwidth costs and information exposure under its privacy budgets),
so its specification argues that these costs are justified by greater end-user benefits.

> This feature is meant to make it easier to write websites
> and to have no negative effects on end-users.
> When websites are easier to write,
> users get more of them
> and don't need to pay as much (in fees or ads)
> to access them.
> [If it's not obvious:]
> See <code>&lt;a href="#<var ignore>later-section</var>"></code>below`</a>`
> for an analysis of why the proposed solution doesn't harm end-users.

## Performance ## {#performance-user-benefit}

> This feature is meant to improve website performance,
> which helps users waste less time waiting
> and helps users on low-end devices and slow connections
> browse the web at all.

## Security ## {#security-user-benefit}

> This feature is meant to improve website security,
> which reduces the frequency of breaches that compromise user data.