Rework Honesty section #27

marcoscaceres · 2025-09-17T07:26:07Z

Close #1

This pull request updates the "Honesty" section of the index.bs file to clarify and expand on the responsibilities of user agents in explaining web activity to users. The revision emphasizes the importance of clear, truthful, and timely explanations using various modalities, and highlights the need to avoid ambiguity and ensure users are informed about sensitive activities.

Clarification and expansion of user agent responsibilities:

Rewrote the "Honesty" section to specify that user agents must explain web activity in ways users can readily understand, using multiple modalities such as prompts, indicators, and cues.
Added guidance that explanations should be truthful, avoid ambiguity, and clearly indicate sensitive activities like audio/video capture.
Stressed the importance of timing and cadence to ensure explanations are helpful and not distracting, supporting informed user choices.

Preview | Diff

Copilot

Pull Request Overview

This pull request reworks the "Honesty" section to provide more comprehensive guidance on how user agents should explain web activity to users. The revision emphasizes clear communication through multiple modalities and the importance of truthful, timely explanations.

Expanded the definition of honesty to clarify user agents' role as mediators between the web and users
Added detailed guidance on explanation methods including prompts, indicators, and other communication modalities
Emphasized the need for truthful representation, avoidance of ambiguity, and clear indication of sensitive activities

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

index.bs

jyasskin · 2025-09-29T23:27:19Z

index.bs

-so that they actually help the user understand
-instead of interrupting and distracting the user.
+A user agent must mediate between the Web and its user,
+explaining what is happening in a form the user can readily understand.


Suggested change

explaining what is happening in a form the user can readily understand.

explaining what is happening in a form the user can easily understand.

?

Probably "can understand" is sufficient without any adjective.

index.bs

jyasskin · 2025-09-29T23:28:51Z

index.bs

+These explanations serve the duty of honesty:
+they should truthfully represent the current state and likely consequences,


Is the first clause adding anything? Could we simplify it to

Suggested change

These explanations serve the duty of honesty:

they should truthfully represent the current state and likely consequences,

These explanations

should truthfully represent the current state and likely consequences,

This was how I was linking it back to the "Honesty" heading, so would prefer to keep it as is... it clarifies what we mean by "honesty".

If we have to explain what "honesty" means, maybe we should say it directly instead of implying it. Something like

Suggested change

These explanations serve the duty of honesty:

they should truthfully represent the current state and likely consequences,

An honest user agent actively works to present the truth to its user.

It doesn't just avoid lies.

Its explanations

should clearly represent the current state and likely consequences,

?

index.bs

jyasskin · 2025-09-29T23:33:26Z

index.bs

+
+Timing and cadence should be chosen deliberately,
+so explanations arrive when helpful and inform rather than distract,
+helping the user make informed choices.


This last clause also feels tacked-on. It might work better as an independent sentence, possible at a different point in this section.

jyasskin · 2025-09-29T23:33:56Z

index.bs

 </div>


 ## Honesty ## {#honesty}


#1 asks whether "honesty" is the right word for what's in this section. Do you feel like it is the right word?

I did... I also couldn't find a better word and it ("honesty") captures the right intent.

index.bs

Co-authored-by: Jeffrey Yasskin <[email protected]>

marcoscaceres · 2025-09-30T03:44:14Z

index.bs

+The user agent should choose when and how often to show these explanations,
+so explanations arrive when helpful and inform rather than distract,
+helping the user make informed choices.


@jyasskin, how about:

Suggested change

The user agent should choose when and how often to show these explanations,

so explanations arrive when helpful and inform rather than distract,

helping the user make informed choices.

The user agent should choose timing and cadence deliberately.

Explanations should inform, not distract, leaving the user in control of if and when to make a decision.

Yes, although we should leave the improvement to the first part of the sentence...

Suggested change

The user agent should choose when and how often to show these explanations,

so explanations arrive when helpful and inform rather than distract,

helping the user make informed choices.

The user agent should choose when and how often to show these explanations,

so explanations arrive when helpful and inform rather than distract.

The user agent should ensure the user can control if and when they make a decision.

jyasskin · 2025-10-06T23:10:38Z

index.bs

+explaining what is happening in a form the user can understand.

+A user agent may use multiple approaches for explanations, including
+text, permission prompts, indicators, previews, placement and emphasis, and other cues.


Can you link to examples of each of these? "Indicators" and "previews", especially, seem to need more context than most readers will have.

"Placement and emphasis" doesn't seem like an approach for an explanation, but rather how to display some other approach. It could belong in a separate sentence?

jyasskin · 2025-10-06T23:12:38Z

index.bs

-These explanations should happen at appropriate times and frequencies,
-so that they actually help the user understand
-instead of interrupting and distracting the user.
+A user agent must mediate between the Web and its user,


I'm worried that "mediate" is less clear than "explain". It's also symmetric, treating the interests of the Web as equal to the user's interests. I'm not completely opposed to using it, but I want to make sure we're trying to follow https://github.com/w3ctag/process/blob/main/style-guide.md as much as possible.

After discussion in Breakout A, I don't feel strongly about this.

jyasskin · 2025-10-06T23:16:48Z

index.bs

+These explanations serve the duty of honesty:
+they should truthfully represent the current state and likely consequences,


If we have to explain what "honesty" means, maybe we should say it directly instead of implying it. Something like

Suggested change

These explanations serve the duty of honesty:

they should truthfully represent the current state and likely consequences,

An honest user agent actively works to present the truth to its user.

It doesn't just avoid lies.

Its explanations

should clearly represent the current state and likely consequences,

?

jyasskin · 2025-10-06T23:21:08Z

index.bs

+The user agent should choose when and how often to show these explanations,
+so explanations arrive when helpful and inform rather than distract,
+helping the user make informed choices.


Yes, although we should leave the improvement to the first part of the sentence...

Suggested change

The user agent should choose when and how often to show these explanations,

so explanations arrive when helpful and inform rather than distract,

helping the user make informed choices.

The user agent should choose when and how often to show these explanations,

so explanations arrive when helpful and inform rather than distract.

The user agent should ensure the user can control if and when they make a decision.

jyasskin · 2025-10-06T23:23:16Z

index.bs

+and make it obvious when sensitive activity is occurring
+(e.g., a clear indicator while audio/video capture is active).


Perhaps we could shorten this sentence:

Suggested change

and make it obvious when sensitive activity is occurring

(e.g., a clear indicator while audio/video capture is active).

and make it obvious when sensitive activity is occurring.

For example, the user agent might show a clear indicator while audio or video is being captured.

Rework Honsty section

d2b2509

marcoscaceres requested a review from Copilot September 17, 2025 07:30

Copilot AI reviewed Sep 17, 2025

View reviewed changes

marcoscaceres commented Sep 17, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

marcoscaceres commented Sep 17, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

marcoscaceres added 2 commits September 17, 2025 16:23

Update index.bs

7d6aa5a

Update index.bs

a44e8dc

marcoscaceres commented Sep 17, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

Apply suggestions from code review

13af2b8

jyasskin requested changes Sep 29, 2025

View reviewed changes

marcoscaceres commented Sep 30, 2025

View reviewed changes

index.bs Outdated Show resolved Hide resolved

marcoscaceres and others added 3 commits September 30, 2025 11:38

Update index.bs

6ddf053

Update index.bs

7e4880d

Co-authored-by: Jeffrey Yasskin <[email protected]>

Update index.bs

589cc2e

Co-authored-by: Jeffrey Yasskin <[email protected]>

marcoscaceres commented Sep 30, 2025

View reviewed changes

marcoscaceres requested a review from jyasskin October 3, 2025 08:10

jyasskin reviewed Oct 6, 2025

View reviewed changes

	explaining what is happening in a form the user can readily understand.
	explaining what is happening in a form the user can easily understand.

		These explanations serve the duty of honesty:
		they should truthfully represent the current state and likely consequences,

-These explanations serve the duty of honesty:
-they should truthfully represent the current state and likely consequences,
+An honest user agent actively works to present the truth to its user.
+It doesn't just avoid lies.
+Its explanations
+should clearly represent the current state and likely consequences,

		and make it obvious when sensitive activity is occurring
		(e.g., a clear indicator while audio/video capture is active).

Rework Honesty section #27

Are you sure you want to change the base?

Rework Honesty section #27

Uh oh!

Conversation

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

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marcoscaceres Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marcoscaceres Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marcoscaceres commented Sep 17, 2025 •

edited by pr-preview bot

Loading

marcoscaceres Sep 30, 2025 •

edited

Loading

marcoscaceres Sep 30, 2025 •

edited

Loading