-
Notifications
You must be signed in to change notification settings - Fork 2
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.
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
Changes from 2 commits
f6d99fe
c4f27df
be662e3
0497b49
2e0aa34
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 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. | ||
|
||
|
|
||
| ## Write Simply ## {#write-simply} | ||
|
|
||
|
|
||
There was a problem hiding this comment.
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"?
There was a problem hiding this comment.
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".