Discussion: Reviewing the py-rse appendices

[DamienIrving]

As it stands there are a number of appendices in our py-rse book. Here's some initial thoughts about where they all belong (and whether we need any others) to get the conversation started.

These appendices are uncontroversial/necessary for the physical book:

• License: LICENSE.md
• Learning Objectives: py-rse/objectives.Rmd
• Key Points: py-rse/keypoints.Rmd
• Glossary: currently gloss.Rmd but maybe we need a system to create a unique glossary for each book which each take a subset of the entries from gloss.Rmd?

These appendices will be online but not in the physical book:

• Setting Up: py-rse/install.Rmd (see #435)
• Solutions: py-rse/solutions.Rmd
• Contributing: CONTRIBUTING.md
• Code of Conduct: CONDUCT.md

(In other words, in the introduction chapter of the physical book we will tell people to go to the website / GitHub repo associated with the book to find information about setting up, solutions to the exercises and contributing. This allows us to continually update the setup instructions and answers to the exercises as time goes on and provides a mechanism for people to contribute their own better solutions.)

These appendices are currently included but don't necessarily have to be:

• Code Style: py-rse/style.Rmd
• Working Remotely: py-rse/ssh.Rmd
• YAML: py-rse/yaml.Rmd

I think we also need an additional appendix to explain the conda-verse. In the setup we meet Anaconda, in provenance.md export the details of our conda environment and in packaging.md we create a new conda environment and as an exercise create a conda package, but we never take a step back to explain what conda/miniconda/anaconda is/are and how they relate to things like conda-forge, which is kind of a must-know for people releasing new python packages. There are existing Carpentries lessons that provide a basic overview of the conda-verse here and here, so we could just take some of the content from those.

Thoughts?

[DamienIrving]

There is also the final tree listing appendix suggested in #432

[DamienIrving]

We discussed this at the meeting on 13 August and decided that I would prepare a conda appendix and final directory tree appendix and keep all the others (i.e. YAML, working remotely, style).

Ultimately the publisher will decide whether things like the solutions and installation instructions go in the printed version of the book.