merely-useful / py-rse

Research Software Engineering with Python course material
http://third-bit.com/py-rse/
Other
246 stars 63 forks source link

Split the introduction chapter in two #506

Closed DamienIrving closed 3 years ago

DamienIrving commented 3 years ago

Most of the current introduction chapter is about course details (the big picture, license, audience, syllabus, acknowledgements, dedications). This content needs to be moved into a numberless prologue (perhaps called "Overview" or "Welcome"), along with a new "how to use this book" section (see below) and some text on how to contribute to the book.

Chapter 1 (which we might rename "Getting Started" or something) should then just contain the initial course content. That includes the existing Project Structure content and possibly also the software installation and data download instructions currently in Appendix E and Section 1.2.1.

How to use this book

Our suggestions on "how to use this book" could be as simple as -- "Work through each chapter, following along with the commands and changes described in the text. Try at least half of the exercises for each chapter" -- to something as complex as an appendix with suggestions for a suggested course plan, adapting these materials to a lecture, finding a mentor or someone to help you (if doing self-study), etc.

Other notes from the reviewer (@ChristinaLK) include:

Cleaning up appendices

Once the new prologue is complete, we should be able to remove appendices A, B and C. See this discussion for details.

gvwilson commented 3 years ago

@lwjohnst86 can you please do this one, since it involves figuring out how to unnumbered preface sections in Bookdown?

lwjohnst86 commented 3 years ago

Sounds good.