Skip to content

Writing a TA Guide

Purpose

This is documentation for how to write modified versions of student project guides for TAs to consult when preparing for and holding office hours.

TA guides exist for two reasons:

  1. As a way for TAs to quickly learn the ins and outs of the project, and provide the most helpful advice, especially for common bugs and important learning objectives.
  2. To eliminate any possibility of students having access to reference solutions. TAs cannot consult reference solutions during office hours, so these guides are what they should rely on instead.

The fundamental principle is: If you couldn’t look at the reference solution, what would be most helpful for you to use when leading office hours? Try to capture as much of that information as you can—remember, you’ll be using these too!

Contents

TA guides contain all of the information from the student guides, with additional annotations. These should be placed at the point in the guide most relevant to that topic. Each type of information should be preceded by one of the following tags, with the tag surrounded by {% color c %}tag:{% endcolor %}, where c is the color specified below:

  • Ask: Questions that TAs might ask students if they're stuck conceptually to nudge them in the right direction. Asks should be LightSkyBlue
  • Ex: "Ask: Can we use the coordinates as they are once we've split them and checked their length? Why not?"
  • Warning: Either implementation quirks that may be easily overseen / missed by students, or edge cases to consider. Warnings should be DarkOrange.
  • Ex: "Warning: Edge case: Illustrate zero-indexing."
  • Example: An example that a TA can walk through a student with. Examples should be DarkViolet. If such examples are also complicated to solve, solutions should be provided to save TAs time and brainpower. Note that edge case examples should NOT be marked as examples, and should instead be marked as Warnings.
  • Ex: "Example: 'I love CS1'.split(' ') --> ['I', 'love', 'CS1']"
  • Insight: Some part of the task that is important for the student to realize. Insight should be colored MediumOrchid
  • Ex: “Insight: We want the students to learn to look at the relevant interface files to understand what methods they should write and what those methods should do.”
  • Ex: "Insight: It's important for students to understand difference between and and or."
  • Advice: advice the TA may give that does not fundamentally help the student solve the problem. The line between advice and insight can be fuzzy, so use your best judgement! Advice should be colored LightPink.
  • Ex: "Advice: If the student presents an approach using conditionals, ensure that their syntax is correct and then ask if they can think of another way to approach the problem without conditional."
  • Ex: "Advice: Students should read the codebase to try and understand what is going on. They are not expected to understand everything."
  • Q&A pairs: lists of common student questions or bugs, with answers to said questions/bugs. If documentation or other resources are referenced here, then the appropriate link should be included. Q's should be colored DodgerBlue and A's MediumSeaGreen.
  • Ex: “‘Q: I’m getting errors when trying to perform operations with my HashTable?’

A: They’re probably initializing with IDictionary<K,V>[] instead of the generic IDictionary[].” - Ex: “Q: ‘My C tests for ArrayDeque fail, and it seems like my Deque contains multiple of the same item?’

A: Their for loop in addFront is copying in the wrong direction (from the front, instead of from the back).” - BAD: any code a student should not write or anything a TA should not do/say. The entire statement should be colored Crimson in this case, not just the tag. - Ex: From CS1 Project 1: "BAD: Students do not know what a method is, refer to it as a function." - Anything else which is easy to read, not a reference solution, and useful! If you want to suggest another category, please contact the professor(s) or Head TAs.

Implementation

TA guides are, like student guides, written in Markdown. The professor(s) or a head TA should be able to provide you access to a git repository containing the guide.

There are three key Markdown environments used. (Adam has configured these to work as described.) Each has a beginning and ending tag, as demonstrated below.

  1. {% faq %}
    This creates a red box in the left-hand margin next to the point at which you placed it. This should be used for debugging help, Q&A pairs, and other minutiae and practicalities. {% endfaq %}
  2. {% ta %}
    This creates a yellow box in the right-hand margin next to the point at which you placed it. This should be used for advice about teaching/learning objectives, high-level algorithm overviews, and other more general comments.
    {% endta %}
  3. {% psuedocode %}
    This creates an accordion section in the guide at the point at which you placed it. It’s labeled “Pseudocode” and can be clicked to reveal its contents. This should be used for providing algorithmic overviews when they’re too long or detailed to fit in the margins.
    {% endpsuedocode %}

Note that the boxes in the margins will (often) overlap unless you manually space them out with {\% tabreak x %} tags, where x is the number of pixels of spacing.

In addition to this, because the student and TA guides are written in the same file, you should surround any information that won't be helpful for TAs (such as grading policies, deadline information, setup, etc) with the {% studentonly %} and {% endstudentonly %} tags. These will be hidden under an "ommitted" dropdown in TA guides.

When creating or editing a TA guide it will be helpful to be able to make and see changes locally. For more information on that visit our page on launching the course website locally: https://readings.caltech.codes/ta-howtos/website/#running-the-website

When looking through a finished TA guide, your faq-blocks and ta-blocks should be roughly balanced for most tasks.

Example