Download as PDF, PPTX
Uploaded bynelle varoquaux
Docathon: How to write (good) documentation
This document discusses best practices for writing documentation. It explains that documentation is important for users to understand how to install and use a project, and for contributors to understand how to contribute. The document outlines different types of documentation including installation instructions, user guides, API references, examples, and tutorials. It also discusses formats like HTML, PDF and interactive help. The document provides examples of well documented projects and gives tips for documentation quality like maintaining examples, writing documentation alongside code, and considering your audience. It recommends tools for documentation and provides guidance on where new users and contributors should start with documentation.
More Related Content
Similar to Docathon: How to write (good) documentation
Docathon: How to write (good) documentation
- 1. Docathon How to write(good) documentation
- 2.
- 3. Why documentation? “Documentation isimportant 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. “
- 4. Why documentation? ● Foryou 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.
- 5. Different types ofdocumentation ● 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
- 6. Different formats ofdocumentation ● 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
- 7. What type ofdocumentation do people use?
- 8. What format ofdocumentation do people use?
- 9. Which type ofdocumentation is most often neglected?
- 10. Examples of welldocumented projects ● Python ○ Scikit-learn ○ numpy ○ Django ○ Mne ○ nilearn ● R ○ ggplot2 ○ caret ○ shiny ○ rcpp
- 11. Key elements tothink 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.
- 12. Key elements tothink 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.
- 13. Key elements tothink about when writing documentation Rule n°3: Documentation is about communication ● Who is your audience? ● How to organize your ideas? ● Visual communication…
- 14. Documentation in practice Tools,guidelines and next steps for improving documentation
- 15. 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
- 16. 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
- 17. 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”
- 18. How to getusers 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.
- 19.
- 20.