“One thing that open-source can’t get enough of is documentation”
I have finally completed my official period as a Technical Writer at
FluxML, and I have enjoyed every second of it! This blog serves as a summary of the work done during the second half of my time at
FluxML. You'd notice that the contributions listed in this blog would cover the entire
FluxML ecosystem and not just
Flux.jl. Furthermore, I will also list some additional documentation contributions made to the much larger
Julia ecosystem during this period!
A quick introduction to
FluxML, quoting their documentation -
Flux is a 100% pure-Julia stack and provides lightweight abstractions on top of Julia's native GPU and AD support. It makes the easy things easy while remaining fully hackable.
Flux is a library for machine learning geared towards high-performance production pipelines. It comes "batteries-included" with many useful tools built in, but also lets you use the full power of the Julia language where you need it.
Honestly, the nature of my work at
FluxML diverged so quickly that summarising it would be a difficult task, but I will try my best! Buckle up! Psst, you can find more about the first half of the time spent at
Getting started section
Let's start from where I left the last blog - the new "Getting Started" section. The good news is that
Flux has a better structured "Getting Started" section now! The bad news is that I did not work on it, but the second good news is that it turned out better than the one I had in mind!
Flux had a lot of tutorials and examples, but they were scattered around and very hard to navigate through. The old “Getting Started” section, “Overview” section, and “Basics” section had valuable information for beginners, but the information was scattered among these three sections. Now, all of these sections have been combined (a huge thanks to
@mcabbott) in a single "Getting Started" section in
Flux's docs! We still have a Getting Started page on
Flux's website, but it will be either migrated or scrapped very soon!
Have a look at the new "Getting Started" section here.
The new (and different than the one I imagined) "Getting Started" prompted a discussion on revamping the existing "Tutorials" section present on
FluxML's website. This section is currently heavily outdated and is not updated very regularly, which often misguides or scares newcomers.
We are planning to migrate these tutorials to
Flux's documentation to keep them up-to-date using doctests. The contents I initially planned for the new "Getting Started" section are now planned to go into the revamped "Tutorials" section.
Have a look at the new "Tutorials" section here.
Independent docs for NNlib.jl
NNlib now has standalone docs!
NNlib's documentation used to live as an independent page under
Flux's documentation, which was not helpful, as
NNlib is an independent
Julia package. This was not convenient for both the users and the developers of
NNlib, as one had to constantly refer to the section in
Flux's documentation to get
My work here started with migrating the existing page from
Flux's documentation to
NNlib, which was then iterated through helpful reviews! This page was then included in a brand new documentation infrastructure, which was merged way back, but the documentation did not appear live until a few days back. The delay in the deployment of the documentation was caused by a few minor
DOCUMENTER_KEY related bugs which have been resolved.
Have a look at
NNlib's updated and independent documentation here.
Revamped docs for Metalhead.jl
Metalhead.jl saw a great amount of development this summer, thanks to a GSoC project led by
@darsnack. With all of this development, it was required to revamp the old
Publish.jl infrastructure to a modern
Documenter.jl infrastructure. This invited numerous discussions from FluxML maintainers, given that both the packages have their ups and downs, but in the end, everyone agreed to migrate
Metalhead's docs to
I aimed for a 1:1 port, not adding any information and not removing any information in the porting process, and the new documentation looks beautiful!
Have a look at
Metalhead's revamped documentation here.
Better community health
I have noticed that
Julia's ecosystem can be a bit daunting for new contributors because of the missing "Community Health" files. Most of the repositories under
FluxML lacked issue and PR templates, making the review and triage process harder than it should be.
FluxML also lacked an organization-wide README, recently introduced by GitHub.
FluxML now has default issues and PR templates, which can be overridden by every repository! The organization-wide README is also in its place, guiding newcomers better than ever!
Have a look at the default issue templates here.
Have a look at the organization-wide README here.
Create a PR in a repository under
FluxML to see the default PR template 😉
Better docs for OneHotArrays.jl
Flux.jl maintainers recently decided to move the "One Hot Encoding" functionalities of
Flux into a separate independent package. As you might have guessed, this called for some documentation audits!
I have updated and added the docstrings of the
OneHot* structs to
OneHotArray's manual, making them accessible to the users. I also debugged and helped to build the missing
v0.1.0 documentation of
Have a look at
v0.1.0 documentation here.
Migrating FluxML's website to Franklin.jl
Franklin.jl is a modern static site generator written in
Julia! Quoting their documentation -
Franklin is a simple, customisable static site generator oriented towards technical blogging and light, fast-loading pages.
FluxML maintainers decided to port the existing
FluxML website (built using
Franklin, and this was primarily carried out by
@darsnack. Where do I come in? I helped set up the infrastructure of the new site! I primarily worked on enabling PR previews using GitHub Actions, something not documented in
Franklin's documentation (and has not been done before). I also fixed some minor bugs revolving around relative paths and production deployment!
Have a look at the migrated website here.
Adding a new section to Franklin.jl's docs 😉
Referring to the section above, I decided to update
Franklin.jl's documentation to include a section on deploying PR previews using GitHub Actions. This eliminated the need for extra infrastructure and also lead to restructuring the original "deploy" documentation of
Franklin. The revamped "deploy" documentation provides much more options to a user and is easier to navigate through.
I also took the liberty to update outdated documentation of
Franklin, including outdated GitHub Actions and variable definitions!
Have a look at the revamped deployment page here.
I cannot possibly think of writing this section without missing out on something. I worked extensively on miscellaneous issues, not limited only to
Flux.jl, but also related to
FluxML as a whole. These miscellaneous issues ranged from refining existing
FluxML's logos to developing and fixing CI/CD pipelines of
Additionally, while working with
Franklin.jl, I discovered that
Julia's website is open-source and written in
Franklin! I took this opportunity to update some outdated Actions and syntax on the website. Currently, I am also looking at migrating Julia's website to the new GitHub Pages infrastructure, or the new PR preview infrastructure (mentioned in the section above).
Refer to my GitHub for all the "misc" work carried out by me during the past six months 🙂
Minor code contributions 😉
Surprisingly, I also contributed to
Flux's code. The code contributions weren't in the form of feature additions, instead, I worked on minor bugs and refined the public API.
For instance, I deprecated
rng_from_array() in the favor of
default_rng_value(), and then marked it as
@non_differentiable. These contributions weren't too big, but adding code to
Flux's repository did feel good. I look forward to writing more code for
FluxML in the future!
I will be forever grateful to the whole FluxML community for giving me such a wonderful time! I do feel like I have accomplished a bit in the last 6 months, and the documentation of FluxML is at a better place than the point when I started.
A special thanks to
@darsnack for bearing with me through my untidy PRs and helping me out as always!
Oh, I also joined FluxML's GitHub organisation a few weeks back! 🥳
PRs and issues
Either I created these PRs/issues, or I had some significant involvement in them 😄
- Fix the last remaining 404 errors
- Better docs for reexported packages
- Leftover changes from #2046
- Add a dark mode version of logo
- Fix a few crossrefs + update Zygote's page
- Make rng_from_array non differentiable
- Back to create_bias
- Add GH action format check files with JuliaFormatter
- @autosize does not work with semi-colon separated kwargs
- Discussion: documentation for @reexported and imported (or using) packages
- Add minimal infrastructure for the docs
- Create root level index.html
- Trigger tagbot on issue comments
- Create independent documentation for NNlib.jl?
- Use the latest API of MLDatasets.MNIST
- Use relative folder paths instead of root paths to fix previews
- Port website to Franklin.jl
- Discussion: Update and periodically test posts and model-zoo tutorials
- New section on previews using GH Actions + update outdated deployment workflows
- Rendering and deploying previews using GitHub
- Indent YAML block
- Update outdated Actions and syntax for variable definition
- Use the new github pages deployment workflow
Top comments (2)
Wow, So cool. At the end, may I ask you how did you create this beautiful thread table of contents?
This was not done by me. I am assuming Julia Forem's maintainer did this (thank you!). You can do this while creating the post -