Issues with the first draft

[LiamPattinson]

I'm collating all issues I'm aware of with my first draft here. These can be spun off into separate issues if we need somewhere to talk about individual issues in more detail.

General

• The lesson assumes students are comfortable using a bash-like shell, but makes no accommodations for Windows users (although Powershell is usually pretty similar), nor does it accommodate those who work through an IDE.
• Episode 3 introduces the use of venv to manage Python environments, but not conda. I personally prefer venv as it's lightweight and ships with Python's standard library (and isn't prone to mangling your PATH), but since conda is so widely used by researchers it'd be a good idea to teach both.
• Poetry is also widely used nowadays, which does the jobs of pip, setuptools, venv, build, and twine. It also automates the task of creating new packages. I'd prefer not to teach it exclusively, but it may be worth including an overview somewhere.
• Should include an episode on writing in-code documentation and using Sphinx.
• Should include an episode on testing with PyTest.
• Possibly could include an episode on automated testing/publishing with GitHub workflows.
• Needs more instructor notes throughout the course.
• Lesson teaching times need updating.
• Some episodes could be split into smaller chunks.

Optional Content

• The optional episode 4 on the evolution of packaging tools isn't well suited for a workshop lesson, and might be better placed in a blog post somewhere.
  • If we do decide to keep it, it may be worth including information on alternative build systems like Poetry and Flit here.
• Some of the other optional content interspersed throughout the lesson is tangential to the core aims, and might be distracting. This currently includes the use of argparse to develop high-quality scripting interfaces, best practices incorporating Matplotlib into a library, and some advanced versioning info.
  • It might be better to collate the scripting bits into a new episode on 'Advanced Scripting' towards the end of the lesson, which could cover everything from if __name__ == "__main__" in a single module to the use of subparsers in packages.
  • It may also be a good idea to move the Matplotlib advice into an episode along the lines of 'Improving your Package with the Scientific Python Ecosystem', which could also touch on best practices with NumPy/Pandas, although I'm sure that could be an entire Carpentries lesson just by itself.

The epi_models example library

• It would be handy to have this hosted as an actual repo for students to use.
• When advancing from a single module to a package, the library splits into 'modelling' and 'plotting' sub-packages. I'd argue that this isn't a good design decision, and that it'd be better to add some other features instead. Perhaps it should instead split into SIR and SEIR subpackages?
• While it's useful to have epi_models as a consistent example to refer back to, it also limits student interactivity. At the very least, the first lesson should spend some time discussing potential package ideas for the students before committing to a single example library.

Publishing

• Assumes students are comfortable with git. Is there room in this lesson for a quick overview?
• Very little info is provided on good use of GitHub. Could talk about using Issues and Pull Requests to manage package updates. Should also include some screenshots.