docathon: how to write (good) documentation
TRANSCRIPT
DocathonHow to write (good) documentation
Thanks to our sponsors!
Why documentation?
“Documentation is important because it's one of the first connections
between the human world and the machine world. It helps us effectively
translate our concepts and ideas into the languages that we use to control
machines. “
Why documentation?● For you you will be using your code in 6 months.
● For users you want people to use your code
○ Shows your project exists.
○ Shows how to install it.
○ Shows how to use it.
● For contributors you want people to help out
○ You only have contributors once you have users.
○ Documentation provides a platform for your first contributions.
Different types of documentation● Literal documentation
○ Installation instructions
○ User documentation
○ Contributor documentation
● API documentation
○ What does a function do?
○ How do I use it? What are the arguments I need to provide? What are the default values?
● Examples and galleries
○ How can I put all the pieces together to form a script or a program?
● Tutorials/Guides
○ Use the tools in a package to cover topics in a particular field.
● FAQ/stackoverflow
Different formats of documentation● HTML documentation
○ Website usually with literal, API and gallery/examples documentation
○ Stack overflow
● PDF documentation
○ Equivalent of website, but downloadable.
○ Usually doesn’t include the API
● Interactive documentation
○ Python
■ >>> help(my_function)
○ R
■ > help(limma)
■ > ?limma
What type of documentation do people use?
What format of documentation do people use?
Which type of documentation is most often neglected?
Examples of well documented projects● Python
○ Scikit-learn
○ numpy
○ Django
○ Mne
○ nilearn
● R
○ ggplot2
○ caret
○ shiny
○ rcpp
Key elements to think about when writing documentation
Rule n°1: Documentation is like code : it needs to be maintained
● Favor quality over quantity
● All examples in the documentation should run automatically.
Key elements to think about when writing documentation
Rule n°2: “If it is not documented, it does not exist”
● Write documentation as you write code.
● Documentation driven development.
Key elements to think about when writing documentation
Rule n°3: Documentation is about communication
● Who is your audience?
● How to organize your ideas?
● Visual communication…
Documentation in practiceTools, guidelines and next steps for improving documentation
Tools for documentation● Literal documentation
○ Python
■ Sphinx
■ Doctest
○ R
■ Knitr & LaTeX (pdf)
■ Knitr & R-markdown (html & pdf)
● API documentation
○ Python
■ Docstrings (numpydoc)
■ Doctest
○ R
■ Help files
■ roxygen
● Examples and galleries
○ Python
■ Sphinx-gallery
○ R
■ N/A
Project manager : Where to start?1. A README file with a brief description of the project & installation instructions
2. (A licence)
3. A short example/tutorial
4. API documentation
5. Link to code, issue tracker and mailing list if applicable
6. Literal documentation
7. Contributor documentation
New contributor : Where to start?1. Familiarize yourself with the project
○ Read the tutorial
○ Read the user documentation
○ Read the contributor documentation
○ Is anything unclear? Are there typos or english mistakes?
2. Improve docstrings
○ Of functions
○ Of Examples
3. Find tickets labeled “Documentation”
How to get users to contribute documentation?1. Think about your contribution workflow?
○ Can users install your package easily? Is the package publicly available?
○ Can users contribute easily?
2. Make sure users can get started
○ Write a brief tutorial
○ Write a couple of examples
3. Where are the pain points of your documentation?
○ Create documentation specific tickets and label them clearly as documentation-related.
4. Write a short “how to contribute” guide.
5. Don’t be too nitpicky about documentation patches!
○ Is the patch an improvement? Yes? Just push the green button.
Let’s get started!
The end…