The Julia Language project
Stay organized with collections
Save and categorize content based on your preferences.
This page contains the details of a technical writing project accepted for
Google Season of Docs.
Project summary
- Open source organization:
- The Julia Language
- Technical writer:
- mkg33
- Project name:
- The unified documentation of Scientific Machine Learning
- Project length:
- Long running (5 months)
Project description
I would like to work on the unification of the SciML organization because there is a lot of room for improvement in this area and the completion of this project will undoubtedly provide immediate benefits both to Julia programmers and active contributors/maintainers of SciML. The packages scattered throughout SciML offer some really useful tools but there is always danger that they might go unnoticed (especially by newcomers) simply because the user was unable to discover the package and apply it to the problem at hand.
This is rather frustrating given that the primary purpose of the packages is to reach a wide audience of programmers (beginners and experts alike). In order to avoid the situation described above, I propose to revise the ‘front page’ of the SciML documentation thoroughly and create a sort of hub that users could use to browse related packages and explore the growing ecosystem. It could also serve as a valuable point of reference for more experienced users and allow them to work more efficiently.
First of all, the existing documentation of all individual packages needs revision with respect to the most basic stylistic issues (such as spelling, punctuation, grammar, etc.). To ensure stylistic consistency, SciML needs to have a concrete style guide (indispensable for making retrospective changes and for future reference). It would be a waste of time to start from scratch. Instead, it ought to be based on the existing Julia conventions and include new entires for SciML-specific issues.
Once the style guide has been completed, I intend to revise the current documentation in the second phase of the project. It will make the documentation look more professional and stable. I have already created several pull requests that illustrate my approach to this task. In this phase, I also intend to devise (and implement) an efficient citation system. The very first task will be to update the outdated citations page.
The third phase, arguably the most important one, will involve designing the SciML roadmap, which will emphasize the interplay between the scattered packages. The stronger the cohesion between two packages (with respect to the problem or the code itself), the closer should they appear in the ‘see also’ list. I propose to create two recommendation keys: one for code similarity and one for problem similarity. This way, users would be able to identify other potentially useful packages much faster than by laborious browsing through the respective repositories and documentation. Instead of listing all the possible connections among the packages, I would rather focus on the larger ones and try to present their links with smaller packages (this method will also be extended to updating tutorials where the connection with another package should be pointed out). This approach guarantees that the ‘see also’ lists will be informative without being exhaustive enumerations of package combinations.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-11-08 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-11-08 UTC."],[[["\u003cp\u003eThis Google Season of Docs project focuses on unifying the Scientific Machine Learning (SciML) ecosystem's documentation within the Julia programming language.\u003c/p\u003e\n"],["\u003cp\u003eThe project aims to improve discoverability of SciML packages by creating a central documentation hub and revising individual package documentation.\u003c/p\u003e\n"],["\u003cp\u003eA SciML style guide will be established for consistency, and a system for citations will be implemented.\u003c/p\u003e\n"],["\u003cp\u003eThe project will highlight relationships between packages for easier navigation and understanding of the SciML ecosystem.\u003c/p\u003e\n"],["\u003cp\u003eBy improving documentation and highlighting inter-package relationships, the project aims to enhance the user experience for both newcomers and experienced programmers.\u003c/p\u003e\n"]]],["The project, part of Google Season of Docs, focuses on unifying the documentation for the SciML organization within the Julia Language. Key actions include: revising existing package documentation for stylistic consistency by creating a style guide based on Julia conventions, and developing an efficient citation system. The project will also build a SciML roadmap that highlights the relationships between packages. The goal is to make it easier for users to discover relevant packages and understand their interconnectedness through recommendation keys for code and problem similarity.\n"],null,["This page contains the details of a technical writing project accepted for\nGoogle Season of Docs.\n\nProject summary\n\nOpen source organization:\n: The Julia Language\n\nTechnical writer:\n: mkg33\n\nProject name:\n: The unified documentation of Scientific Machine Learning\n\nProject length:\n: Long running (5 months)\n\nProject description\n\nI would like to work on the unification of the SciML organization because there is a lot of room for improvement in this area and the completion of this project will undoubtedly provide immediate benefits both to Julia programmers and active contributors/maintainers of SciML. The packages scattered throughout SciML offer some really useful tools but there is always danger that they might go unnoticed (especially by newcomers) simply because the user was unable to discover the package and apply it to the problem at hand.\n\nThis is rather frustrating given that the primary purpose of the packages is to reach a wide audience of programmers (beginners and experts alike). In order to avoid the situation described above, I propose to revise the 'front page' of the SciML documentation thoroughly and create a sort of hub that users could use to browse related packages and explore the growing ecosystem. It could also serve as a valuable point of reference for more experienced users and allow them to work more efficiently.\n\nFirst of all, the existing documentation of all individual packages needs revision with respect to the most basic stylistic issues (such as spelling, punctuation, grammar, etc.). To ensure stylistic consistency, SciML needs to have a concrete style guide (indispensable for making retrospective changes and for future reference). It would be a waste of time to start from scratch. Instead, it ought to be based on the existing Julia conventions and include new entires for SciML-specific issues.\n\nOnce the style guide has been completed, I intend to revise the current documentation in the second phase of the project. It will make the documentation look more professional and stable. I have already created several pull requests that illustrate my approach to this task. In this phase, I also intend to devise (and implement) an efficient citation system. The very first task will be to update the outdated citations page.\n\nThe third phase, arguably the most important one, will involve designing the SciML roadmap, which will emphasize the interplay between the scattered packages. The stronger the cohesion between two packages (with respect to the problem or the code itself), the closer should they appear in the 'see also' list. I propose to create two recommendation keys: one for code similarity and one for problem similarity. This way, users would be able to identify other potentially useful packages much faster than by laborious browsing through the respective repositories and documentation. Instead of listing all the possible connections among the packages, I would rather focus on the larger ones and try to present their links with smaller packages (this method will also be extended to updating tutorials where the connection with another package should be pointed out). This approach guarantees that the 'see also' lists will be informative without being exhaustive enumerations of package combinations."]]
