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.