Add Project structure and Writing code sections

[robmoss]

I started sketching out content for a project structure section, but this quickly branched out to include a variety of topics that are better described as writing code.

Sources of motivation include:

• Having some content about choosing a project structure ahead of the next malaria group meeting, when we're going to talk about this topic;
• Writing down my key arguments for considering code as a primary research output; and
• Explaining why the way that we approach writing code, and learning to write code, is extremely important.

I want to refer to real examples of public repositories (such as my 2020 COVID-19 forecasts one, which I mention in Project structure / Explain how it all works) and highlight what they do well and what they don't do well.

[github-actions]

PR Preview Action v1.4.7
🚀 Deployed preview to https://robmoss.github.io/git-is-my-lab-book/pr-preview/pr-59/
on branch gh-pages at 2024-04-11 01:13 UTC

[robmoss]

... and now it occurs to me that I should probably end the "Writing code" section with a reminder, or an exercise, to seek feedback on code that you're currently writing (i.e., code that isn't finished) ...

[robmoss]

Scientific Python provides helpful guides on a number of relevant topics, including some general design principles. Some of the topical guides are very detailed and, perhaps, a bit too much detail for our audience.

[robmoss]

We should share this PR with the CoP and ask them to provide suggestions, comments, etc, building on what we covered in yesterday's meeting. We can provide the live preview of the Project structure and Writing code sections.

[robmoss]

@EamonConway I've migrated this PR from mdBook to MkDocs

As per my previous comment, we should consider sharing this PR with the CoP and ask them to provide suggestions, comments, etc. It probably covers some things that are relevant to the orientation guide.

[robmoss]

I've rebased this so that it applies cleanly on the new site structure (Introduction / Orientation / Topical Guides / Community).

[michaelplanknz]

Sorry git novice here so not sure if this is the right place to post this!

As a suggestion for the Orientation section (which already looks super useful), it might be useful to have a few examples of code that are small and self-contained and do some simple task. For example, a function that reads in a long-form CSV data set and returns some aggregated values, e.g. number of occurrences of X on each day between Y and Z. This could serve as an exemplar for how to structure good code (comments, good variable naming, no magic numbers, well defined function inputs/outputs, etc.). It could also include an example of a test function, as I think the idea of automated tests may be a new concept for many (me included!). Ideally, keeping the tasks relatively simple will mean that code doesn't need to use too many language-specific features or packages but can illustrate principles in a language-agnostic way.

Again apologies if this is in the wrong place, please feel free to tell me if I should post this somewhere else!

[robmoss]

Hi @michaelplanknz that's a great suggestion! Having examples that show rather than tell would be really useful.

I've created a new issue #69 to act as a starting point, because it's not directly related to this pull request (absolutely no drama, and apologies for not having clearer instructions on the orientation guide page itself).