--- title: Documentation type: slides order: 1 author: Luisa Orozco, Barbara Vreede, Jaro Camphuijsen, Carlos Martinez, Max Paulus, Robin Richardson --- # Documentation === ## What is documentation? - Provides context for your work - Explains what this is and how to use it - Explains what has been done and why === ## Why document software? Make your software reusable: - A user should be able to run your software in the same way as you do now - A user should be able to install your software - A contributor should be able to add to, improve, or fix code note: "a contributor" includes future you. Don't touch your code for a year or two and you will not immediately remember the decisions that you made in the past. === ## Documentation types Documentation can have different purposes: - **User documentation** - What does the software do? How can it be used? - **Developer documentation** - How can your software be modified or extended? Why were certain development choices made. - **Deployment documentation** - How to install the software? What hardware and other software is needed? === ## Documentation formats - README: simple text file, first thing that users/collaborators see - In-code: intended for developers (comments, docstrings, ...) - Websites, Wikis - Tutorials === ## A good README file + README file is first thing a user/collaborator sees + What should be included in README files?

Note: + A descriptive project title + Motivation (why the project exists) and basics + Installation / How to setup + Copy-pasteable quick start code example + Usage reference (if not elsewhere) + Recommended citation if someone uses it + Other related tools ("see also") + Contact information for the developer(s) + License information + Contributing guidelines === ## In-code documentation? - Code comments: - Provide context for (complex parts) of the code - Explains certain coding decisions - Can often be replaced by better programming - Docstrings: - Special comments that describe (use of) functions/classes/etc. - Can be called by users/websites - Follow a standardized syntax (per programming language) == ## Exercise: In-line comments **Comment A**


# Now we check if temperature is larger than -50:
if temperature > -50:
    print('do something')

**Comment B**


# We regard temperatures below -50 degrees as measurement errors
if temperature > -50:
    print('do something')

- How are these different? Which one do you prefer? - Can you think of a way to avoid using comments altogether? === ## User/API documentation + What if a README file is not enough? + Use tools to create API documentation from existing docstrings note: tools include + **Sphinx** / **mkdocs** (documentation generator) - creates nicely-formatted HTML pages out of .md or .rst files - programming language independent + **Github pages** (deploy your documentation) - set up inside your GitHub repository - automatically deploys documentation generated above === ## Tutorials + Example code that allows users to run specific test cases + Jupyter notebooks are often used for this purpose === ## Take-home message - Documentation is a vital part of a project. - It should be kept and created alongside the corresponding code. - Depending on the purpose/scope documentation needs to meet different criteria. - Documentation can take many shapes. === www.esciencecenter.nl info@esciencecenter.nl 020 - 460 47 70

Software Documentation

Reusability requires good documentation

README

Popular tools foor building more complex documentation