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.

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

Added extra information and user-action summaries to 7 migration docs. #6850

Merged
merged 8 commits into from
Apr 27, 2023

Conversation

ericsnekbytes
Copy link
Collaborator

@ericsnekbytes ericsnekbytes commented Apr 24, 2023

See #6851, this PR adds extra information to the migrate_to_notebook7 doc:

  • A summary of user-actions to take
  • Additional context
  • Formatting/document structure updates

@github-actions
Copy link
Contributor

Binder 👈 Launch a Binder on branch ericsnekbytes/notebook/migrate_to_7_updates

@ericsnekbytes ericsnekbytes marked this pull request as ready for review April 24, 2023 14:52
@ericsnekbytes ericsnekbytes changed the title (DRAFT) Added extra information and user-action summaries to 7 migration docs. Added extra information and user-action summaries to 7 migration docs. Apr 24, 2023
@echarles
Copy link
Member

Thx @ericsnekbytes I have gone across your changes and they make sense to me.

Copy link
Member

@jtpio jtpio left a comment

Choose a reason for hiding this comment

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

Thanks for taking the time to improve the documentation.

Left a couple of comments.

docs/source/migrate_to_notebook7.md Outdated Show resolved Hide resolved
docs/source/migrate_to_notebook7.md Outdated Show resolved Hide resolved

- If you NEED to maintain compatibility with the Classic Notebook for extensions
or other customizations that are critical to your workflows, you can switch to
[nbclassic], the new home for users who need to maintain compatibility with the
Copy link
Member

@jtpio jtpio Apr 25, 2023

Choose a reason for hiding this comment

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

The "new home" and "maintain" words in this sentence give the somewhat misleading idea that nbclassic will be maintained in the long run?

NBClassic is supposed to help with the transition to Notebook 7, but shouldn't be seen as an "alternative" to Notebook 7 long term.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Yeah it's a subtle thing to communicate. We want people who need it to know it's there and to use it, without giving the impression it's a permanent thing. I'll add a bit/re-work to add some clarity. Thanks!

Copy link
Member

Choose a reason for hiding this comment

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

I posted a comment in the team compass issue to see if the EC can provide guidance for the documentation as well, since they will be looking at the blog post: jupyter/notebook-team-compass#24 (comment)

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I have updated this portion with a recent commit, and we can modify as needed after the EC takes a look.

[nbclassic], the new home for users who need to maintain compatibility with the
old notebook interface

## Why things are changing
Copy link
Member

Choose a reason for hiding this comment

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

Maybe something like the following?

Suggested change
## Why things are changing
## Why a new major version?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I think this one is worth keeping, because it simplifies the language and reduces jargon (related to semantic versioning / "major version", which not everyone is going to know about). Maybe there's a plain-language compromise, like "Why the big version change?" Is it the "major-version-number-is-being-incremented-to-7" idea that you want to communicate here?

Copy link
Collaborator Author

@ericsnekbytes ericsnekbytes Apr 26, 2023

Choose a reason for hiding this comment

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

@jtpio Is "Why the big version change?" good? Edit: I've just pushed that, let me know if there's anything else.

Copy link
Member

@jtpio jtpio Apr 27, 2023

Choose a reason for hiding this comment

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

"big" sounds ambiguous: what does big mean?

If this is because of the word "major" then maybe we could just drop it and only keep "Why a new version"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Big was supposed to communicate that sweeping changes are taking place in plain-language (without the "major version" jargon and the odd-sounding/confusing phrasing that it necessitates...."Why a new major version" sounds odd, but "Why a major new version" does not...probably related to points noted in this BBC article...).

I've pushed an update to just "Why a new version?" which I think is good enough, let me know if you've got any other suggestions.

ericsnekbytes and others added 4 commits April 25, 2023 08:37
Co-authored-by: Jeremy Tuloup <jeremy.tuloup@gmail.com>
Co-authored-by: Jeremy Tuloup <jeremy.tuloup@gmail.com>
@jtpio
Copy link
Member

jtpio commented Apr 27, 2023

Looks like it needs a lint pass to fix the CI check (jlpm run prettier should do it).

@ericsnekbytes
Copy link
Collaborator Author

That's done.

@jtpio
Copy link
Member

jtpio commented Apr 27, 2023

Thanks!

@jtpio jtpio merged commit 68f10a2 into jupyter:main Apr 27, 2023
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Apr 28, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants