Skip to content

Say how to explain developer-focused features. #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 27, 2025
Merged

Say how to explain developer-focused features. #30

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f6d99fe
Say how to explain developer-focused features.
jyasskin Jul 25, 2025
c4f27df
Clarify which kind of feature.
jyasskin Jul 30, 2025
be662e3
Re-add the "do explain the user need" and provide boilerplate text fo…
jyasskin Aug 20, 2025
0497b49
Apply Lola's suggestion from today's breakout.
jyasskin Aug 20, 2025
2e0aa34
Put "first, don't harm users" up top.
jyasskin Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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 features designed for authors,
you need to clearly establish that there's no negative effect on end-users.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

*After* proving that end-users aren't harmed,
then you should clearly describe the developer problem you're trying to solve.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!


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

Expand Down