Standardize on "Output" to describe the results of executing a cell

[JasonWeill]

Earlier today I discussed with @ellisonbg the inconsistent wording in the cell contextual (right-click) menu. There are six menu items that refer to either "Output" or "Outputs":

1. Copy Output to Clipboard
2. Create New View for Output
3. Clear Outputs
4. Clear All Outputs
5. Enable Scrolling for Outputs
6. Disable Scrolling for Outputs

Problem

The words "Output" and "Outputs" are used interchangeably to refer collectively to the result of running a cell. The term "All Outputs" is ambiguous: does it refer to all outputs associated with a single cell or to all outputs associated with all cells?

Proposed Solution

Rename the above six items as follows:

1. Copy Output to Clipboard (unchanged)
2. Create New View for Output → Create New View for Cell Output
3. Clear Outputs → Clear Cell Output
4. Clear All Outputs → Clear All Cell Outputs
5. Enable Scrolling for Outputs → Enable Scrolling for Cell Output
6. Disable Scrolling for Outputs → Disable Scrolling for Cell Output

Alternatively, combine menu items 5 and 6 into a single menu item called "Scroll Cell Output" that displays a checkmark if it is enabled.

Document the JupyterLab meaning of the terms "input," "output," and "cell output" in the developer documentation for writers, "User Interface Naming Conventions" subsection. For example, "Notebooks contain cells. Each cell has input and one or more outputs. When the user runs a cell, the kernel reads and executes the input and generates output. The notebook then displays the cell's output. The term output describes one of possibly multiple results of running a cell. The term cell output describes the collective output of one cell."

Additional context

We should have similar guidelines for other languages in case this inconsistency is a problem there as well.

[ellisonbg]

Thanks for opening the issue @jweill-aws The only change I might make to your proposed solution is to change 5/6 to "Enable|Disable Scrolling for Cell Output" to clarify that this is a per-cell action. Also, if the implementation is possible, I like the idea of combining those two into a checkmark/toggle.

[krassowski]

I like the proposed changes (3) and (4), they clarify things. I like (5) and (6) as proposed by @ellisonbg. This still leaves us with an inconsistency between (1) and (2): 1) Copy Output to Clipboard = copies a single output 2) Create New View for Output = creates a view for all outputs of a cell.

Maybe we should also change 2 to Create New View for Cell Output and codify in the docs that we should use:

• Cell Output for all outputs of a cell,
• Output for singular output

Or maybe we could go a step further and modify 1 to Copy Selected Output to Clipboard and forbid using Output without classifier (so it becomes either Cell Output or Selected Output).

[JasonWeill]

@krassowski I hadn't realized that (1) in the above would copy only one output from a cell, using "output" as a countable noun. I had hoped to stop using "output" in this way, but it seems like we still need to distinguish between a single output, all outputs for a cell, and all outputs for all cells.

As an alternative, how about the following definitions: (sentence case for use in prose, Title Case in menus)

• Output for a single output from a cell
• All outputs for this cell
• All outputs for all cells

To save space, we can rewrite (2) to New View for All Outputs for This Cell.

[ellisonbg]

I think the proposal of @krassowski to resolve the ambiguity in (1) and (2) makes sense. I think the most important thing here is that we only use the plural "Outputs" to refer to the "Cell Output" of multiple cells. The reason for this is that while the technical design of the document has a list of outputs for each cell, the mental model of users is likely simpler - "each cell has an input and an output". IOW, I don't believe that most users are strongly aware that a single cell has multiple outputs, so when they see the plural "outputs" they will interpret that to refer to the output of multiple cells. While the most recent phrasing of @jweill-aws is more accurate technically, I think it will still confuse users.

[JasonWeill]

Reflecting @krassowski and @ellisonbg 's comments:

Rename the above six items as follows:

1. Copy Output to Clipboard (unchanged)
2. Create New View for Cell Output
3. Clear Outputs → Clear Cell Output
4. Clear All Outputs → Clear All Outputs (unchanged)
5. Enable Scrolling for Outputs → Enable Scrolling for Cell Output
6. Disable Scrolling for Outputs → Disable Scrolling for Cell Output

[JasonWeill]

Updated the description above with the following item names:

1. Copy Output to Clipboard (unchanged)
2. Create New View for Output → Create New View for Cell Output
3. Clear Outputs → Clear Cell Output
4. Clear All Outputs → Clear All Cell Outputs
5. Enable Scrolling for Outputs → Enable Scrolling for Cell Output
6. Disable Scrolling for Outputs → Disable Scrolling for Cell Output

[JasonWeill]

Removing triage label per conversation with @ellisonbg : looks like we have consensus.

[JasonWeill]

One additional change: Restart Kernel and Clear All Outputs… → Restart Kernel and Clear All Cell Outputs…

[krassowski]

As an alternative, how about the following definitions: (sentence case for use in prose, Title Case in menus)

• Output for a single output from a cell
• All outputs for this cell
• All outputs for all cells

To save space, we can rewrite (2) to New View for All Outputs for This Cell.

Well, I like this one a lot. No strong opinions though. I was also thinking about using a possessive form. I am slightly concerned that some ESL users may have a problem parsing Clear All Cell Outputs correctly, but I don't know common this issue could be. It feels to me that Clear Outputs of All Cells is easier to parse unambiguously (which is btw what is used by VSCode) because you see "Cells" in plural and "Outputs" in plural, and don't have to mentally parse the compound noun (I think that it is not an issue for native speakers though).

[JasonWeill]

I was pleased to see that VSCode also uses Cell Output in its UI. I can modify my PR #11904 to use "Outputs of All Cells" in lieu of "All outputs for all cells" or "All cell outputs"