Workshop: Git for course deployment and websites

November 18, 2019

The Git repository for this workshop is here: https://github.com/massma/ltf-github-website-courses

Learning objectives

Attendees will learn:

How to use Git to manage projects
How to publish a website using Github
How to manage content with simple Markdown text files
How simple text files and Git ease collaboration and rapid development
How we can automatically generate websites, documents, and presentations from simple text files
The pros and cons of using Git as a tool to manage, organize, and collaborate on the deployment of courses

Lectures and slides

Introduction to Git and Github : tools to collaborate and update content.
Using pandoc to automatically generate websites, presentations, and notes : convert simple, portable, and accessible text formats like Markdown to "prettier" representations.

Instructions for contributing

Only modify the markdown (.md) files, not the html or any other files.

Post-event survey

Please fill out this survey after the event. This is my first time doing this, so feedback both helps me improve and helps the CTL improve the Lead Teaching Fellowship program and support.

Resources

Git : version control software that manages projects and allows many people to contribute to a project.
Github : a Microsoft-owned web platform that hosts Git-managed projects and provides tools for users to raise issues and questions on projects and merge their own changes to a project.
Markdown : a simple plain text document format that is very portable and easy to modify.
Pandoc : tool to convert to and from many file formats. For example, it can generate PDFs, websites, and presentations from Markdown text files.

Tools to automate content generation; e.g. "build tools" (these might be OS-specific)

GNU/Linux and Mac OSX
- Gnu Make : simple tool that automatically detects changes in source materials and re-compiles dependencies. In our examples, this involves automatically "compiling" websites and presentations using Pandoc whenever there are changes to the Markdown files.
Windows
- Any help from Windows users on what is used? Could install make with Cygwin, but seems overly complicated.

Alternatives

Gitlab : an alternative to Microsoft's Github. A (possibly biased) comparison with Github is available on Gitlab's website.
Shake : an alternative build system to Make with a little bit more of a learning curve but with more features and the benefits of access to a full programming language in Haskell. I (Adam) use this primarily, mostly because I use Haskell primarily. Many other languages also have build systems, and it can be beneficial to use a build system embedded in the language you prefer (e.g. SCons in Python, Rake in Ruby).
Org mode - an alternative to Markdown with advanced personal organizational tools integrated into the Emacs text editor.

Tutorials

Github guides - collection of useful guides, some of which linked below.
Github Hello World : introduction to Github, and no text editor even required!
Mastering Markdown : Github introduction to Markdown format.
Git tutorial : in depth introduction to Git
Pandoc Getting Started : very thorough and accessible introduction to using Pandoc.
Try Pandoc Online : simple web application that lets you convert text between many formats. Also shows the corresponding Pandoc command for each conversion.

Pros and Cons of Github for course deployment and website design

Pros

Students can contribute to course content, fix errors, and take ownership of the material in a unique way.
"Issues" page acts as a forum like Piazza: students can ask questions and answer each others' questions.
All course materials are in one place, rather than split across websites, Piazza, Courseworks, email, etc.
Students learn tools (Github, Git) that can benefit them in their academic and professional lives.
Course development is transparent: students and teachers can see the history of materials and when/why materials were changed, updated, or added.
Students get credit for their contributions in a formal way ("contributors" page).
All materials are publicly available (e.g. no uni required to access), so others can benefit from the course material.
Course materials are in an accessible and portable format. No proprietary software is required to access or read course material, like Microsoft office.
Facilitates collaboration between TAs and instructors in the development of course materials.

Cons

Students must, depending on their background, learn a new tool.
Students are required to sign up for Github. While it is free cost-wise, some students may not want to sign up for another online account, especially one that is owned by a large corporation like Microsoft.
For many students the delivery of materials with Github may be new and disorienting, and could take some getting used to. This could negatively impact or disadvantage the students who are less familiar with Github and formats like Markdown.

Misc contributions and/or feedback

any random thoughts or contributions put here

Attendees

Adam Massmann (akm2203) : organizer
Chloe Diamond (ccd2120)
Adam Atia (aaa2269)
Yu Huang (yh3019)
Wenli Zhou wz2481
Dianchen Sun (ds3869)
Yaling Liu (yl3937)
Laureline Josset (lj2390)
Prachi Patel (pmp2138)
Yash Amonkar (yva2000)
Weiqian Wang (ww2559)
Minzhi Yang (my2662)
Luping Ye (ly2483)
Jisu Han (jh4147)

The Center for Teaching and learning (CTL) and this workshop

This event is sponsored by the Lead Teaching Fellowship, which is a professional development program for graduate students at Columbia University committed to advancing pedagogy.

The CTL has a lot of great programming that I would recommend for anyone interested in teaching. Specific for doctoral students, there is the CTL Teaching Development Program, the Lead Teaching Fellowship (sponsored this event), the Teaching Observation Fellowship, and Teaching Assessment Fellowship. If you are interested in any of the fellowships, I think enrollment in the Teaching Development Program would strengthen your application.