Visible

Pre-learning materials

Having awesome code isn’t enough on its own. We need to make it easy for others to find, understand, and use - documentation is one of the ways that we can achieve this. For Reproducible Analytical Pipelines, there are several types of documentation, each with their own role to play.

In the previous session, we looked at how to document individual functions, so that users are clear on what each function does. However, function documentation on its own might not be enough for users, because it does not provide an overview of the package or pipeline as a whole. Providing further context and instructions is key to making your code more accessible. Additionally, although you might understand your code today, it might not make sense 12 months later! Documentation is also a way of making your code understandable for your future self.

This section covers three ways of making your code more visible:

• READMEs
• Vignettes and documentation websites
• Licences

Note

Read through the sections below and try out the 👩‍💻 Your turn sections. Share your answers in the shared learning document for your group. We’ll use your comments as discussion points in the contact session.

• Group 1
• Group 2
• Group 3
• Group 4

READMEs

The simplest and most minimal form of documentation is a README. Please read the following article.

📖 Make a README by Danny Guo (10 minutes).

👩‍💻 Your turn

✏️ Write a README for some code that you have written, or for some analysis you have completed (15 minutes). Please be prepared to share and discuss this in the face-to-face session.

Vignettes and documentation sites

Once a README is in place, you may also want to provide more detailed documentation for your code. This is because the README is intended to provide a quick overview, which might not be sufficient on its own. Below are some options for creating more detailed documentation.

R

📖 R Vignettes by Software Carpentry.

Read the article and explore the vignette for one R package of your choice. How does it aid your understanding of the code? What does the vignette provide that the README on its own does not? (30 minutes)

Python

📖 RAP Cookiecutter documentation by NHS England.

Read the documentation site and compare it with the repository README. What are the differences between the two types of documentation? (30 minutes)

Licences

There are many different licences out there. What are our options, if we are to make our code open source? Watch the video below for an overview.

📺 Open source licence types by Pro Tech Show (12 minutes).

What licences are recommended for analytical code by the UK Government Service Manual? What category does this fall under, according to the classifications provided in the video above?

📖 Government Digital Service: Making source code open and reusable (10 minutes)

Before the session

Come prepared to discuss:

• Who are the different audiences for your analysis?
• What are the differences between documentation sites, vignettes, and READMEs?
• Which type of documentation might be best suited for each of your different audiences?
• Why might a licence matter for analytical code?
• Have you read a README or other documentation that was particularly helpful (or unhelpful)? What made the difference?
• What was your experience of writing a README like? Please share the README that you wrote.
• What other ways are there to increase the visibility of your work?

Next steps (optional)

If you wish to extend your learning beyond the scope of this course, try some of the resources below.

• 📺 Writing effective documentation by Beth Aitman (10 minutes)
• ✏️ R: Use {pkgdown} to turn your R vignettes into a documentation site
• ✏️ Python: Use mkdocs to build a basic Python documentation site.
• 📖 Have a look at ATLAS, a directory of open-source tools, packages, and projects for analytics and decision science in healthcare. Consider submitting your work to it.