@@ -98,8 +98,13 @@ Do explain the connection,
98
98
even if this requires breaking the “be brief” rule.
99
99
For example, see the
100
100
[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]] .
103
108
104
109
## Write Simply ## {#write-simply}
105
110
@@ -179,3 +184,59 @@ See this rendered at
179
184
path: template.md
180
185
highlight: markdown
181
186
</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> <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