07-09, 13:30–16:30 (Europe/Amsterdam), TU-Eindhoven 0.242
Wanna learn how to write a stellar documentation, that will satisfy newcomers, make them quickly and efficiently learn your software, and even motivate them to become contributors? Then join this workshop all about one of the most important aspects of software development: documentation! You will learn the core principles of good docs, tips & tricks, and you will write good docs yourself, during the workshop! Plus you'll learn to create docs and host them online using Documenter.jl!
Note: you should bring the codebase you want to document with you in this workshop! The exercises are applied to your own codebase!
This workshop is all about documentation. It's one of the most important aspects of code and software: it makes your code accessible to others, makes their experience with it pleasant, makes them wanna keep using it for the long run, and lowers the threshold for them to become contributors! Whether you are a maintainer of several registered Julia packages, or a just someone with an unregistered codebase that you believe can be useful for others, this workshop will be of use to you!
The workshop will be fully hands-on, and will be composed by several iterations of [lecture -> application] for the covered topics. The main things it will cover are (among others, and depending on the real-time flow):
- Core principles of what makes a good documentation.
- The skeleton of a good documentation: exceptional, unambiguous docstrings.
- The different depths of exposition approach to documentation.
- The introductory tutorial.
- Tips & tricks for increasing clarity in the docs.
- Intro to Documenter.jl: key syntax and functions.
- Using Documenter.jl+Literate.jl to generate a runnable tutorial.
- Layouting documentation pages.
- Using Documenter.jl to compile a documentation locally into HTML.
- Using Documenter.jl to deploy documentation online on a GitHub repository.
- Using DocumenterCitations.jl to cite literature robustly.
- Tips for reducing maintainance burden.
Morten is a physicist & software engineer from Estonia, but based in Auckland, New Zealand. He's one of the maintainers Documenter.jl and the JuliaDocs package ecosystem, and works as a software engineer at JuliaHub.
GitHub: @mortenpi
Software Engineer at JuliaHub.
I am an applied physicist/mathematician with a broad interest in nonlinear dynamics and complex systems and their application to understand the physical world at a conceptual level. My main focus in my research is understanding the interaction of clouds, climate variability, and climate multistability. Besides research, I am the lead developer of the JuliaDynamics software organization, an advocate of open source code and good scientific code practices in academia, and passionate about teaching applied physics/mathematics with a fresh, hands-on computational style