From f6d99fe19b2fea09e655d744df55cc910233f2b8 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Fri, 25 Jul 2025 23:31:33 +0000 Subject: [PATCH 1/5] Say how to explain developer-focused features. And how to tell if a feature actually is developer-focused. --- index.bs | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/index.bs b/index.bs index 2e495f1..61b892f 100644 --- a/index.bs +++ b/index.bs @@ -93,13 +93,22 @@ 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, -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. +Some features are intended to help authors and +have no effect on end-users aside from websites being delivered more cheaply. +For example, [[css-nesting inline|CSS nesting]] primarily makes it easier to write stylesheets, +and the potential effect on 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. + +End-users come before authors +in the [[design-principles#priority-of-constituencies|priority of constituencies]], +so when explaining this kind of feature, +you need to clearly establish that there's no negative effect on end-users. +*After* proving that end-users aren't harmed, +then you should clearly describe the developer problem you're trying to solve. ## Write Simply ## {#write-simply} From c4f27df4c2b213cb850b7352b23dbbc5fa1176a7 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Wed, 30 Jul 2025 17:26:33 +0000 Subject: [PATCH 2/5] Clarify which kind of feature. --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 61b892f..5707ede 100644 --- a/index.bs +++ b/index.bs @@ -105,7 +105,7 @@ so its specification argues that these costs are justified by greater end-user b End-users come before authors in the [[design-principles#priority-of-constituencies|priority of constituencies]], -so when explaining this kind of feature, +so when explaining features designed for authors, you need to clearly establish that there's no negative effect on end-users. *After* proving that end-users aren't harmed, then you should clearly describe the developer problem you're trying to solve. From be662e3cd367c7bfd5a30ab52a677de8de00d47a Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Wed, 20 Aug 2025 04:20:59 +0000 Subject: [PATCH 3/5] Re-add the "do explain the user need" and provide boilerplate text for doing that. And other responses to review comments. --- index.bs | 83 ++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 68 insertions(+), 15 deletions(-) diff --git a/index.bs b/index.bs index 5707ede..dfe96eb 100644 --- a/index.bs +++ b/index.bs @@ -93,22 +93,19 @@ 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). -Some features are intended to help authors and -have no effect on end-users aside from websites being delivered more cheaply. -For example, [[css-nesting inline|CSS nesting]] primarily makes it easier to write stylesheets, -and the potential effect on 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. +Sometimes the connection to the end-user need is complicated. +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), +and see [[#boilerplate-user-benefit]] for text to +explain why security boundaries are important for users. -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. -*After* proving that end-users aren't harmed, -then you should clearly describe the developer problem you're trying to solve. +Some features are intended to help authors and +have no effect on end-users aside from websites being developed more easily. +See [[#authoring-user-benefit|the boilerplate for ease of authoring]] +for some constraints on this category +and boilerplate to use in this case. ## Write Simply ## {#write-simply} @@ -188,3 +185,59 @@ See this rendered at path: template.md highlight: markdown + +# 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 effect on 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 <a href="#later-section">below`` +> 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. From 0497b49b17c0e145202921e2b24eda1fa4e9acd7 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Wed, 20 Aug 2025 10:43:57 -0700 Subject: [PATCH 4/5] Apply Lola's suggestion from today's breakout. --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index dfe96eb..e15617f 100644 --- a/index.bs +++ b/index.bs @@ -213,7 +213,7 @@ 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 effect on file sizes wasn't measured as part of justifying the feature. +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 From 2e0aa34b57e7234f034d2a0ca2246be48fdcb44d Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Mon, 25 Aug 2025 20:21:50 -0700 Subject: [PATCH 5/5] Put "first, don't harm users" up top. --- index.bs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index e15617f..a3ce320 100644 --- a/index.bs +++ b/index.bs @@ -103,9 +103,8 @@ 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. -See [[#authoring-user-benefit|the boilerplate for ease of authoring]] -for some constraints on this category -and boilerplate to use in this case. +If your feature doesn't cause any harm or benefit to users, +use [[#authoring-user-benefit|the boilerplate for ease of authoring]]. ## Write Simply ## {#write-simply}