Writing and Maintaining Exceptional Documentation | JuliaCon 2024 Workshop
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 to application] for the covered topics. The main things it will cover are (among others, and depending on the real-time flow):
1. Core principles of what makes a good documentation.
2. The skeleton of a good documentation: exceptional, unambiguous docstrings.
3. The different depths of exposition approach to documentation.
4. The introductory tutorial.
5. Tips & tricks for increasing clarity in the docs.
6. Intro to Documenter.jl: key syntax and functions.
7. Using Documenter.jl+Literate.jl to generate a runnable tutorial.
8. Layouting documentation pages.
9. Using Documenter.jl to compile a documentation locally into HTML.
10. Using Documenter.jl to deploy documentation online on a GitHub repository.
11. Using DocumenterCitations.jl to cite literature robustly.
12. Tips for reducing maintainance burden.