Modern Scientific Authoring: Lesson Design

Process Used

This lesson was developed using a slimmed-down variant of the “Understanding by Design” process. The main sections are:

  1. Assumptions about audience, time, etc. (The current draft also includes some conclusions and decisions in this section - that should be refactored.)

  2. Desired results: overall goals, summative assessments at half-day granularity, what learners will be able to do, what learners will know.

  3. Learning plan: each episode has a heading that summarizes what will be covered, then estimates time that will be spent on teaching and on exercises, while the exercises are given as bullet points.

Stage 1: Assumptions

As stated in “Good Enough Practices in Scientific Computing”:

  1. Make text accessible to yourself and others now and in the future
  2. Reduce chances of work being lost or people overwriting each other’s work.
  3. Make it easy to track and combine contributions from multiple collaborators.
  4. Avoid duplication and manual entry of information, particularly in constructing bibliographies, tables of contents, and lists
  5. Make it easy to regenerate the final shared form (e.g., the PDF), and to tell if the PDF in hand is up to date.
  6. Make it easy to share the final version with collaborators and submit it to journals

We recommend against traditional desktop tools like LibreOffice and Microsoft Word because they make collaboration difficult: six people mailing each other copies of a paper with “Track Changes” enabled is a sure way to lose work (and time). The nerd alternative is:

  1. Manuscripts are written in a plain text format such as LaTeX or Markdown that plays nicely with version control
  2. Tools needed to compile manuscripts are managed just like tools used to do simulation or analysis

But as Stephen Turner said, “…try to explain the notion of compiling a document to an overworked physician you collaborate with. Oh, but before that, you have to explain the difference between plain text and word processing. And text editors. And Markdown/LaTeX compilers. And BiBTeX. And Git. And GitHub. Etc. Meanwhile he/she is getting paged from the OR…”

We therefore also support an alternative to text + version control:

  1. Manuscripts are written using Google Docs or some other online tools with rich formatting and change tracking
  2. A short text file is added to the doc directory with metadata about each online manuscript
    • Just as the data directory might contain links rather than actual data
  3. The manuscript is downloaded and saved in doc in an editable form (e.g., .docx or .odt) after major changes

The justification is:

Stage 2: Desired Results



I can…


I know…

Stage 3: Assessment

Summative Assessment

  1. Convert a Markdown document to a Google Doc to share with collaborators.
  2. Publish the same document as a single-page website with GitHub Pages.

Introduction (9:00)

Basic Markdown (09:25)

Translating Markdown (09:40)

GitHub Pages (10:05)

Coffee (10:35): 10 min

Reviewing Material on GitHub (10:45)

Open Publication and Review (11:05)

Tracking Work (11:25)

Working with Others (11:55)

Wrap-Up (12:10)

Finish (12:30)