Say how to explain developer-focused features. #30

jyasskin · 2025-07-25T23:35:03Z

And how to tell if a feature actually is developer-focused.

Fixes #7. @mikewest @torgo @lolaodelola, how'd I do?

And how to tell if a feature actually is developer-focused.

index.bs

hadleybeeman · 2025-08-06T17:39:57Z

I think both the (proposed) deleted text and the (proposed) added text are worth including. I recommend we keep them both.

mikewest

Thanks, @jyasskin. This looks pretty reasonable to me, and I've left a few nits inline that might be worth discussing.

mikewest · 2025-08-11T19:14:41Z

index.bs

-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.


"delivered more cheaply" seems limited. That is, it's possible for a feature that doesn't otherwise surface itself to end-users to provide benefits to their privacy, security, bandwidth usage, performance characteristics, etc, generally through some developer-facing ergonomic improvement.

Perhaps "developed more easily/correctly"?

If a web feature provides benefits to users (privacy, security, bandwidth usage, performance, etc), I think the explainer should just say that, and not try to say that it's a developer-focused feature. I think we mentioned providing some template text for those. I'll see what that looks like in an appendix here...

I've adopted your suggestion of "developed more easily".

mikewest · 2025-08-12T07:16:40Z

index.bs

+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.


The spirit of this advice seems quite reasonable, but it seems impractical to begin an explainer with a discussion of how a given proposal won't harm users. To me, it seems necessary to motivate and explain a proposal somehow prior to making claims about its implications.

I'd suggest y'all recommend that proposals with tradeoffs clearly explain those considerations and justify themselves as being beneficial to end-users, but leave it up to the author to decide how to structure that discussion.

Good point. I've moved this block into the "boilerplate" appendix and suggested linking to a later section with more analysis. How does this look?

I really liked the up-front-ness around the importance of establishing that a proposal doesn't cause harm.

But reading @mikewest's comment has clarified why in some cases that would actually make it harder to read - so yes, allowing the author to structure that argument is fine by me.

However, it looks like that clause about avoiding harm to users has disappeared from the latest diff. Whilst I agree with giving the author a bit more freedom with respect to structure, I do think a clause like this needs to be prominent in the explainer explainer, as it helps set expectations that this is still really important, even if in some cases the justification will come later in the document.

https://pr-preview.s3.amazonaws.com/jyasskin/explainer-explainer/pull/30.html#authoring-user-benefit still starts with

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

But I'd be fine with also saying something about avoiding harm in the earlier section. I've added suggested text for that. Feel free to merge it or suggest something different if you had something else in mind.

ACK - bearing in mind both the note about establishing there's no negative effect on end-users, and the suggested text you mentioned that mentions 'harm' near the start of the document, I am happy with this; thanks!

mikewest · 2025-08-12T07:21:55Z

index.bs

+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.


I'd suggest "no net negative effect", as it seems possible for even the most well-meaning of features to have tradeoffs. Those should be explained and justified, as discussed below, but it seems impractical to treat any negative effect as ending the conversation.

I feel like it's hard to be sure that the net effect is non-negative for everyone once there are some negative effects. If there are both positive and negative effects on users, I feel like the explainer ought to focus on those effects rather than moving onto developer effects. It's only when there really aren't any negative effects that it makes sense to go to the next level of the Priority of Constituencies.

…r doing that. And other responses to review comments.

jyasskin

Thanks for the reviews. @hadleybeeman, I re-added the deleted text.

@mikewest I added a boilerplate appendix to give examples of describing the connection to user need.

jyasskin · 2025-08-20T03:31:26Z

index.bs

-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.


If a web feature provides benefits to users (privacy, security, bandwidth usage, performance, etc), I think the explainer should just say that, and not try to say that it's a developer-focused feature. I think we mentioned providing some template text for those. I'll see what that looks like in an appendix here...

I've adopted your suggestion of "developed more easily".

jyasskin · 2025-08-20T03:34:26Z

index.bs

+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.


I feel like it's hard to be sure that the net effect is non-negative for everyone once there are some negative effects. If there are both positive and negative effects on users, I feel like the explainer ought to focus on those effects rather than moving onto developer effects. It's only when there really aren't any negative effects that it makes sense to go to the next level of the Priority of Constituencies.

jyasskin · 2025-08-20T04:03:34Z

index.bs

+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.


Good point. I've moved this block into the "boilerplate" appendix and suggested linking to a later section with more analysis. How does this look?

index.bs

jyasskin · 2025-08-21T22:11:50Z

index.bs

+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.


https://pr-preview.s3.amazonaws.com/jyasskin/explainer-explainer/pull/30.html#authoring-user-benefit still starts with

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

But I'd be fine with also saying something about avoiding harm in the earlier section. I've added suggested text for that. Feel free to merge it or suggest something different if you had something else in mind.

index.bs

martinthomson · 2025-08-26T03:22:59Z

index.bs

+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]].


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

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.

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

SHA: 0d4cb99 Reason: push, by jyasskin Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Say how to explain developer-focused features.

f6d99fe

And how to tell if a feature actually is developer-focused.

lolaodelola reviewed Jul 30, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

Clarify which kind of feature.

c4f27df

jyasskin requested review from matatk and hadleybeeman July 30, 2025 18:05

mikewest reviewed Aug 12, 2025

View reviewed changes

Re-add the "do explain the user need" and provide boilerplate text fo…

be662e3

…r doing that. And other responses to review comments.

jyasskin commented Aug 20, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

Apply Lola's suggestion from today's breakout.

0497b49

jyasskin commented Aug 21, 2025

View reviewed changes

Put "first, don't harm users" up top.

2e0aa34

martinthomson reviewed Aug 26, 2025

View reviewed changes

jyasskin merged commit 0d4cb99 into w3ctag:main Aug 27, 2025
1 check passed

jyasskin deleted the end-user-need branch August 27, 2025 17:14

github-actions bot added a commit that referenced this pull request Aug 27, 2025

Say how to explain developer-focused features. (#30)

47a22d4

SHA: 0d4cb99 Reason: push, by jyasskin Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Say how to explain developer-focused features. #30

Say how to explain developer-focused features. #30

Uh oh!

Conversation

jyasskin commented Jul 25, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

hadleybeeman commented Aug 6, 2025

Uh oh!

mikewest left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jyasskin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jyasskin commented Jul 25, 2025 •

edited by pr-preview bot

Loading