@@ -98,8 +98,13 @@ Do explain the connection,
9898even if this requires breaking the “be brief” rule.
9999For 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
179184path: template.md
180185highlight: 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> <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