-
-
Notifications
You must be signed in to change notification settings - Fork 5.5k
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
Conversation
There was a problem hiding this 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
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? |
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. |
…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.
…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)
…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)
…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.
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.