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

Move profiling manual section to a new tutorials toplevel heading #52056

Merged
merged 1 commit into from
Nov 9, 2023

Conversation

LilithHafner
Copy link
Member

This creates a new "Tutorials" section to contain the tutorial-esque content scattered throughout the existing documentation. This section may be moved to a separate repo in the future to ease maintenance.

Organization inspired both by https://diataxis.fr/ and by the desire to make it easier to contribute to Julia documentation. Some documentation PRs receive pushback for being too tutorialy, and this would provide an alternative avenue for those contributors.

@LilithHafner LilithHafner added docs This change adds or pertains to documentation docsystem The documentation building system labels Nov 7, 2023
Copy link
Member

@c42f c42f left a comment

Choose a reason for hiding this comment

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

I'm kinda surprised by how simple this turned out to be.

I think we should do it!

  • We need a proper place for tutorials so tutorial-like PRs don't get rejected and so that people can write actual tutorials content with the correct audience in mind.
  • This tutorial for a stdlib doesn't fit under the Manual heading which largely contains language-related content

@LilithHafner LilithHafner merged commit 137783f into master Nov 9, 2023
9 checks passed
@LilithHafner LilithHafner deleted the lh/tutorials branch November 9, 2023 04:38
@KristofferC
Copy link
Sponsor Member

We need a proper place for tutorials so tutorial-like PRs don't get rejected and so that people can write actual tutorials content with the correct audience in mind.

I don't think the manual for the language is the right place for this though. There is an almost unbounded number of tutorials that can be written (as shown by https://julialang.org/learning/tutorials/). Are you saying that these tutorials ideally should be in the language manual?

@LilithHafner
Copy link
Member Author

Some tutorials (e.g. this tutorial for how to launch the repl) do belong on the docs.julialang.org page. I do agree, however, that it would be nice, where it makes sense, to splice out these essential tutorials from more formal and less newbie-friendly content to leave the manual more specification/reference like without loosing the utility of docs.julialang.org to help new users. Hence the tutorials section to put them in and link to them.

KristofferC added a commit that referenced this pull request May 6, 2024
fredrikekre pushed a commit that referenced this pull request May 7, 2024
…ding (#52056)" (#54374)

This reverts commit 137783f.

I think there are many problems with the new Tutorial toplevel section:

- It should be very important since it adds a full new toplevel section
(to the existing five). However, it basically does not contain anything.
It was created by a somewhat arbitrary move of a manual-entry to the
tutorial section as well as a single page that more or less only
contains an external link.

- There is a non-obvious overlap between the Manual entries and the
Tutorial entries. The profiling entry was moved to tutorials but you
could take more or less any other entry in the manual entry and move it
as well.

- The comment in
#52056 (review)
says
> We need a proper place for tutorials so tutorial-like PRs don't get
rejected and so that people can write actual tutorials content with the
correct audience in mind

While this might be true I don't think it is obvious at all that the
manual needs to be the place where people can "dump" general tutorials
about things. Right now, the Tutorial-section has more or less
"unbounded scope" and it isn't clear at all what should go in there.

- It has been there for 7 months without any real activity (except
taking a (again somewhat arbitrary) piece of the Pkg documentation into
it) so it seems it isn't really used for anything.

  
Considering all of the above, I think it is best to go back to the
status quo of 1.10 instead of "locking this in" for 1.11.
KristofferC added a commit that referenced this pull request May 20, 2024
…ding (#52056)" (#54374)

This reverts commit 137783f.

I think there are many problems with the new Tutorial toplevel section:

- It should be very important since it adds a full new toplevel section
(to the existing five). However, it basically does not contain anything.
It was created by a somewhat arbitrary move of a manual-entry to the
tutorial section as well as a single page that more or less only
contains an external link.

- There is a non-obvious overlap between the Manual entries and the
Tutorial entries. The profiling entry was moved to tutorials but you
could take more or less any other entry in the manual entry and move it
as well.

- The comment in
#52056 (review)
says
> We need a proper place for tutorials so tutorial-like PRs don't get
rejected and so that people can write actual tutorials content with the
correct audience in mind

While this might be true I don't think it is obvious at all that the
manual needs to be the place where people can "dump" general tutorials
about things. Right now, the Tutorial-section has more or less
"unbounded scope" and it isn't clear at all what should go in there.

- It has been there for 7 months without any real activity (except
taking a (again somewhat arbitrary) piece of the Pkg documentation into
it) so it seems it isn't really used for anything.

Considering all of the above, I think it is best to go back to the
status quo of 1.10 instead of "locking this in" for 1.11.

(cherry picked from commit 54dc748)
KristofferC added a commit that referenced this pull request May 23, 2024
…ding (#52056)" (#54374)

This reverts commit 137783f.

I think there are many problems with the new Tutorial toplevel section:

- It should be very important since it adds a full new toplevel section
(to the existing five). However, it basically does not contain anything.
It was created by a somewhat arbitrary move of a manual-entry to the
tutorial section as well as a single page that more or less only
contains an external link.

- There is a non-obvious overlap between the Manual entries and the
Tutorial entries. The profiling entry was moved to tutorials but you
could take more or less any other entry in the manual entry and move it
as well.

- The comment in
#52056 (review)
says
> We need a proper place for tutorials so tutorial-like PRs don't get
rejected and so that people can write actual tutorials content with the
correct audience in mind

While this might be true I don't think it is obvious at all that the
manual needs to be the place where people can "dump" general tutorials
about things. Right now, the Tutorial-section has more or less
"unbounded scope" and it isn't clear at all what should go in there.

- It has been there for 7 months without any real activity (except
taking a (again somewhat arbitrary) piece of the Pkg documentation into
it) so it seems it isn't really used for anything.

Considering all of the above, I think it is best to go back to the
status quo of 1.10 instead of "locking this in" for 1.11.

(cherry picked from commit 54dc748)
lazarusA pushed a commit to lazarusA/julia that referenced this pull request Jul 12, 2024
…ding (JuliaLang#52056)" (JuliaLang#54374)

This reverts commit 137783f.

I think there are many problems with the new Tutorial toplevel section:

- It should be very important since it adds a full new toplevel section
(to the existing five). However, it basically does not contain anything.
It was created by a somewhat arbitrary move of a manual-entry to the
tutorial section as well as a single page that more or less only
contains an external link.

- There is a non-obvious overlap between the Manual entries and the
Tutorial entries. The profiling entry was moved to tutorials but you
could take more or less any other entry in the manual entry and move it
as well.

- The comment in
JuliaLang#52056 (review)
says
> We need a proper place for tutorials so tutorial-like PRs don't get
rejected and so that people can write actual tutorials content with the
correct audience in mind

While this might be true I don't think it is obvious at all that the
manual needs to be the place where people can "dump" general tutorials
about things. Right now, the Tutorial-section has more or less
"unbounded scope" and it isn't clear at all what should go in there.

- It has been there for 7 months without any real activity (except
taking a (again somewhat arbitrary) piece of the Pkg documentation into
it) so it seems it isn't really used for anything.

  
Considering all of the above, I think it is best to go back to the
status quo of 1.10 instead of "locking this in" for 1.11.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This change adds or pertains to documentation docsystem The documentation building system
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants