Skip to content

Commit 0d4cb99

Browse files
authored
Say how to explain developer-focused features. (#30)
And how to tell if a feature actually is developer-focused.
1 parent 30c67e4 commit 0d4cb99

File tree

1 file changed

+63
-2
lines changed

1 file changed

+63
-2
lines changed

index.bs

Lines changed: 63 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,8 +98,13 @@ Do explain the connection,
9898
even if this requires breaking the “be brief” rule.
9999
For example, see the
100100
[explainer for deprecating `document.domain`](https://github.com/mikewest/deprecating-document-domain/#a-problem),
101-
although even that could perhaps use another sentence
102-
explaining why security boundaries are important for users.
101+
and see [[#boilerplate-user-benefit]] for text to
102+
explain why security boundaries are important for users.
103+
104+
Some features are intended to help authors and
105+
have no effect on end-users aside from websites being developed more easily.
106+
If your feature doesn't cause any harm or benefit to users,
107+
use [[#authoring-user-benefit|the boilerplate for ease of authoring]].
103108

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

@@ -179,3 +184,59 @@ See this rendered at
179184
path: template.md
180185
highlight: markdown
181186
</pre>
187+
188+
# Appendix B: Boilerplate Explanations of User Benefit # {#boilerplate-user-benefit}
189+
190+
Some classes of features are meant to
191+
help authors achieve some kind of user benefit,
192+
like security, accessibility, or performance,
193+
more easily.
194+
Explainers for these features should say why that general area helps users,
195+
but explainer authors should
196+
spend most of their time explaining why the feature improves the area.
197+
This section provides some boilerplate for some common areas
198+
so that authors don't need to rewrite it every time.
199+
200+
## Accessibility ## {#accessibility-user-benefit}
201+
202+
> This feature is meant to improve website accessibility,
203+
> which ensures all users can browse the web,
204+
> even if they need to interact with their computers
205+
> differently from the majority.
206+
207+
## Ease of Authoring ## {#authoring-user-benefit}
208+
209+
End-users come before authors
210+
in the [[design-principles#priority-of-constituencies|priority of constituencies]],
211+
so when explaining features designed for authors,
212+
you need to clearly establish that there's no negative effect on end-users.
213+
214+
For example, [[css-nesting inline|CSS nesting]] primarily makes it easier to write stylesheets,
215+
and the potential reduction in file sizes wasn't measured as part of justifying the feature.
216+
On the other hand,
217+
a feature like [[privacy-preserving-attribution inline|Privacy-Preserving Attribution]]
218+
isn't in this category because it does have some negative effect on end-users
219+
(via bandwidth costs and information exposure under its privacy budgets),
220+
so its specification argues that these costs are justified by greater end-user benefits.
221+
222+
> This feature is meant to make it easier to write websites
223+
> and to have no negative effects on end-users.
224+
> When websites are easier to write,
225+
> users get more of them
226+
> and don't need to pay as much (in fees or ads)
227+
> to access them.
228+
> [If it's not obvious:]
229+
> See <code>&lt;a href="#<var ignore>later-section</var>"></code>below`</a>`
230+
> for an analysis of why the proposed solution doesn't harm end-users.
231+
232+
## Performance ## {#performance-user-benefit}
233+
234+
> This feature is meant to improve website performance,
235+
> which helps users waste less time waiting
236+
> and helps users on low-end devices and slow connections
237+
> browse the web at all.
238+
239+
## Security ## {#security-user-benefit}
240+
241+
> This feature is meant to improve website security,
242+
> which reduces the frequency of breaches that compromise user data.

0 commit comments

Comments
 (0)