This lesson was developed using a slimmed-down variant of the “Understanding by Design” process.
The main sections are:
Assumptions about audience, time, etc.
(The current draft also includes some conclusions and decisions in this
section - that should be refactored.)
Desired results:
overall goals, summative assessments at half-day granularity, what learners
will be able to do, what learners will know.
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
Audience
Graduate students or equivalent in all fields from astronomy to the digital humanities
Who are writing, publishing, and managing papers, theses, grant proposals, lessons, etc.
Make text accessible to yourself and others now and in the future
Reduce chances of work being lost or people overwriting each other’s work.
Make it easy to track and combine contributions from multiple collaborators.
Avoid duplication and manual entry of information,
particularly in constructing bibliographies, tables of contents, and lists
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.
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:
Manuscripts are written in a plain text format such as LaTeX or Markdown that plays nicely with version control
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:
Manuscripts are written using Google Docs or some other online tools with rich formatting and change tracking
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
The manuscript is downloaded and saved in doc in an editable form (e.g., .docx or .odt) after major changes
The justification is:
If the document lives online (Google Docs or Authorea),
then everyone’s changes are in one place,
and hence don’t need to be merged manually.
If the document lives in a version control system (GitHub),
it provides good support for finding and merging differences resulting from concurrent changes.
Stage 2: Desired Results
Questions
How do I make my work more accessible to others in my field?
How do I collaborate with colleagues while writing?
How do publishers and researchers keep track of who published what?
How can open access publication and open review be implemented?
What are their pros and cons?
Skills
I can…
…write and review research-related documents in Google Docs
…write research-related documents in Markdown
…review documents on GitHub
…turn Markdown into PDF or HTML using Pandoc
…publish Markdown using GitHub Pages and Jekyll
…comment on a web page using hypothes.is
…add my ORCID to electronic manuscripts
…get a DOI for a publication from Zenodo
Knowledge
I know…
…the difference between WYSIWYG formats and markup