Skip to content
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

Jump to bottom

Add content for new notebook page #27382

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add content for new notebook page #27382

wants to merge 3 commits into from
+624 −258

Conversation

estherk15
Copy link
Contributor

@estherk15 estherk15 commented Jan 30, 2025 •
edited by jira bot
Loading

What does this PR do? What is the motivation?

The Notebooks product is undergoing a revamp and will be available in Preview next Wednesday

  • This is an MVP documentation, a lot of the content is copied over from legacy docs.
  • There are plans to break this information up, to clean up structure, and to add more images. But this is the MVP so product engineering can send this to prospective customers for content.
  • Editorial Review: DOCS-9979

Merge instructions

Merge readiness:

  • Ready for merge

Merge queue is enabled in this repo. To have it automatically merged after it receives the required reviews, create the PR (from a branch that follows the <yourname>/description naming convention) and then add the following PR comment:

/merge

Additional notes

@estherk15 estherk15 requested review from a team as code owners January 30, 2025 21:18
@github-actions github-actions bot added Architecture Everything related to the Doc backend Images Images are added/removed with this PR labels Jan 30, 2025
@github-actions GitHub Actions
Copy link
Contributor

Preview links (active after the build_preview check completes)

New or renamed files

Modified Files

@estherk15 estherk15 added the editorial review Waiting on a more in-depth review label Jan 30, 2025
janine-c
janine-c reviewed Jan 31, 2025
View reviewed changes
Copy link
Contributor

@janine-c janine-c left a comment

Choose a reason for hiding this comment

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

This was a beast, Esther, nicely done! I made some copyedit and formatting suggestions - don't hesitate to let me know if you'd like to chat about any of them, if you'd like me to take another look, or any other way I can help 😀

content/en/notebooks/notebooks_legacy.md

## Overview

Notebooks combine graphs and text in a linear, cell-based format. They help you explore and share stories with your data by creating postmortems, investigations, runbooks, documentation, and more.
Copy link
Contributor

Choose a reason for hiding this comment

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

I know this is existing content, so I won't spend too much time on it 🙂 This phrasing gave me pause for a sec, though, because it made it sound like we were telling people to tell stories to their data 😂

Suggested change
Notebooks combine graphs and text in a linear, cell-based format. They help you explore and share stories with your data by creating postmortems, investigations, runbooks, documentation, and more.
Notebooks combine graphs and text in a linear, cell-based format. They help you explore and create stories with your data, using postmortems, investigations, runbooks, documentation, and more.

content/en/notebooks/notebooks_legacy.md
Comment on lines +59 to +65
You can switch between modes from within the Notebook by selecting the dropdown at the top right of your notebook.

- **Editing**: make changes to the notebook.

- **Viewing**: contents are Read Only, preventing users from making unwanted edits to existing configurations and information.

- **Presenting**: share the contents of the Notebook in a display format where each cell appears as a slide. Presentation mode supports graph interactions such as tooltips and legends.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
You can switch between modes from within the Notebook by selecting the dropdown at the top right of your notebook.
- **Editing**: make changes to the notebook.
- **Viewing**: contents are Read Only, preventing users from making unwanted edits to existing configurations and information.
- **Presenting**: share the contents of the Notebook in a display format where each cell appears as a slide. Presentation mode supports graph interactions such as tooltips and legends.
You can switch between modes from within the notebook by selecting the dropdown at the top right of your notebook.
- **Editing**: make changes to the notebook.
- **Viewing**: contents are Read Only, preventing users from making unwanted edits to existing configurations and information.
- **Presenting**: share the contents of the notebook in a display format where each cell appears as a slide. Presentation mode supports graph interactions such as tooltips and legends.

content/en/notebooks/notebooks_legacy.md
* **All Notebooks**: All Notebooks in your organization.
* **[Notebook Type](#notebook-types)**: Group notebooks by type.

Hover over the Preview icon for any Notebook to see a preview of the contents, including widget types and Markdown. To open the Notebook in [View Mode](#view-mode), hover over the notebook and click **Open notebook in view mode** on the right.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
Hover over the Preview icon for any Notebook to see a preview of the contents, including widget types and Markdown. To open the Notebook in [View Mode](#view-mode), hover over the notebook and click **Open notebook in view mode** on the right.
Hover over the Preview icon for any notebook to see a preview of the contents, including widget types and Markdown. To open the notebook in [View Mode](#view-mode), hover over the notebook and click **Open notebook in view mode** on the right.

content/en/notebooks/notebooks_legacy.md

### Notebook types

{{< img src="notebooks/add_notebook_type.png" alt="Add Type button highlighted in a Notebook" style="width:100%;">}}
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
{{< img src="notebooks/add_notebook_type.png" alt="Add Type button highlighted in a Notebook" style="width:100%;">}}
{{< img src="notebooks/add_notebook_type.png" alt="Add Type button highlighted in a notebook" style="width:100%;">}}

content/en/notebooks/notebooks_legacy.md

#### Layout options

In a Notebook cell, click **Edit** to view the cell configuration in edit mode. You can also see the available layout options, which vary based on the cell content type, but include the following:
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
In a Notebook cell, click **Edit** to view the cell configuration in edit mode. You can also see the available layout options, which vary based on the cell content type, but include the following:
In a notebook cell, click **Edit** to view the cell configuration in edit mode. You can also see the available layout options, which vary based on the cell content type, but include the following:

content/en/notebooks/notebooks_new.md

### Version history

From a notebook, click the **Configure** icon and click **Version history** to open the Version History side panel. You can preview, restore, or clone your notebook's version history. For more information, see the [Version History guide][18].
Copy link
Contributor

Choose a reason for hiding this comment

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

Is the Configure icon different from the cog icon? If they're the same thing, I like how you referred to it here - I like referring to what icons are for, so people can think about the objectives they're trying to accomplish, instead of looking for specific icons that can be harder to remember if there are many of them.

content/en/notebooks/notebooks_new.md
1. Use the dropdown to select one or more roles, teams, or users that may edit the notebook.
1. Click **Add**.
1. The dialog box updates to show that the role you selected has the **Editor** permission.
1. Click **Save**
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
1. Click **Save**
1. Click **Save**.

content/en/notebooks/notebooks_new.md

**Note:** To maintain your edit access to the notebook, the system requires you to include at least one role that you are a member of before saving.

To restore general access to a notebook with restricted access, follow the steps below:
Copy link
Contributor

Choose a reason for hiding this comment

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

As above, do you need Editor access for this?

content/en/notebooks/notebooks_new.md

### Search

The search field supports document text search. Type what you're looking for and the notebooks below will list the results.
Copy link
Contributor

Choose a reason for hiding this comment

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

As above, is a document a different thing here?

content/en/notebooks/notebooks_new.md

Notebooks APIs are currently being updated to support the new Notebooks product. Creating notebooks through the API places them in "compatibility mode," supporting only markdown and widget cells.

You cannot read or edit new notebooks using the notebooks API; attempts to do so will result in a 400 error.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
You cannot read or edit new notebooks using the notebooks API; attempts to do so will result in a 400 error.
You cannot read or edit new notebooks using the notebooks API; attempts to do so result in a 400 error.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@janine-c janine-c janine-c left review comments

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
Architecture Everything related to the Doc backend editorial review Waiting on a more in-depth review Images Images are added/removed with this PR
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@estherk15 @janine-c