Lessons learned while working as a technical writer at FluxML

Acme Design is a full service design agency.

JuliaCon 2023

Saransh Chopra

Tidbits about me

  • Undergrad majoring in CS and Maths
  • Likes Python and Julia
  • Was a Technical Writer at FluxML
  • Likes Open-Source Scientific Software
  • Maintains a few of them
  • Contributes to a lot of them!

Clever documentation will push away beginners and newcomers 

Lesson 1

The documentation and examples in FluxML were convoluted with complex looking simple code which resulted in problems like this -

While starting out with FluxML, I faced the exact same issues as well

Hence, it is critical to ensure that the examples are not unnecessarily complicated

There are no "perfect" docstrings

Lesson 2

I realised that everyone had a different perception of "perfect" docs, including me

I do write bad code, but my simple documentation PRs were getting more change requests than my bad code PRs

Patience is the key! Incorporate best bits from everyone's "perfect" docstring!

Doctests make documentation much more maintainable in the longer run

Lesson 3

Great, another testing suite that developers can collectively hate

  • These missing or outdated examples were pushing beginners away

Problem

Solution

  • Add strict doctests for every user facing API iteratively
  • Test the example scripts/notebooks in every CI run
  • Mandatorily update doctests with every new API change
  • We had regular complaints of outdated examples + docstrings + tutorials + model zoo

Results

A lot of examples and docstrings were indeed outdated, and all of them were caught by doctests

Now the examples will ideally never go stale ;)

Unless someone turns off the doctests :(

Broken cross-references and links are a big let down for everyone

Lesson 4

Hate these pages? So do your package's users!

FluxML had a huge number of broken links and cross-references, because, they were not checked anywhere

USE LINK CHECKERS! USE DOCUMENTER'S INBUILT FEATURES TO AVOID SUCH PAGES!

Scattered docs make it really hard to navigate to the right content, driving away beginners from your package

Lesson 5

  • The tutorials and guides were scattered across the website, docs, and model-zoo.

  • The API docs were mixed with the guides

Problem

Solution

  • Proper segregation between API docs, guides, and tutorials.
  • Revamping the doc structure
  • Connecting the packages with each other in their respective docs
  • The old FluxML docs had no proper structure.
documentation.divio.com

Utility infrastructure for documentation will make your life smooth and investing your time in developing it is worth it

Lesson 6

Welp, another failing CI badge, but this time for documentation

Need to review a documentation PR? Well, you better run the branch locally to check if the docs are rendering correctly

A new bug reported with no MWE? I think I might have to comment and remind the author to write an MWE

Nice, a new PR with 50 changed files, but wait, there's no description

Splitting up your package?

Set up documentation previews on PRs. Set up a bot to comment preview links on command. Write custom workflows for Franklin.jl previews. Worth the time! Cue: Flux.jl + fluxml.github.io

Set up issue and PR templates. Worth the time! Cue: FluxML

Split the workflows and documentation infrastructure too! Cue: NNlib.jl

Revamping an outdated package?

Migrate to the latest documentation tools! Cue: Metalhead.jl

FluxML has all of them, and we LOVE it

For students planning to work on Julia's ecosystem

DOCUMENT YOUR WORK!!!

Thank You!

saransh-cpp.github.io

Made with Slides.com