Proofreading captions as a technical reviewer

As a technical reviewer, your job is to proofread the captions for our videos. That means watching the video with captions enabled, and correcting any mistakes that you notice. Our transcriptionist does a great job of capturing the conversation, but a lot of the technical terminology is unfamiliar to her. We need you to check that the technical terminology is correct.

You will be assigned a 15-30 minute portion of video to review. We get full coverage by assigning different portions of video to other technical reviewers.

The captions are provided as a SubRipText (.srt) file, which is a plain text format. You can make corrections using your choice of text editor.

Get ready to review

Before you begin reviewing captions you'll have to:

• download the video (you should receive a link in an email from SendOwl)
• create your own fork of the captions repository and clone it locally
• (or if you already have your own fork: pull down the latest changes from the fromPeerToPeer base fork)
• check out the proofreading-{guestname}-captions branch and commit your changes in that branch
• install the VLC media player
• open the video and .srt files using VLC media player

Read our how to create a PR article for help with forking your repository.

Read our how to watch a video with captions article for help getting set up with VLC media player.

When you've done all of that, you're ready to start proofreading captions.

Meet the SubRip text format

Here's a snippet from an .srt file:

1
00:00:01,450 --> 00:00:02,810
Welcome to Peer to Peer

2
00:00:02,820 --> 00:00:05,650
where you can watch our
experts solve tech problems.

Each caption is made up of 3 things:

• the caption number
• the timestamps, marking the start and end times for each caption
• the caption text

As a technical reviewer, we ask that you pay attention only to the caption text. Our transcriptionist is responsible for getting the timings right.

Your text editor may not have built-in support for .srt files. If you want to enable syntax highlighting for you text editor, check out these links:

• for Sublime Text: Sublime-Subtitles-Highligher
• for Vim: vim-subrip
• for emacs: srt-mode

What to look for

• technical terminology that has been transcribed incorrectly
• technical terminology that our transcriptionist has marked as inaudible, but you can make out
• spelling mistakes (we use US English)
• grammatical errors (only if you are certain!)

Here are a few example corrections:

• s/recurser/recursively (incorrectly transcribed technical term)
• s/low path/load path
• s/git in it/git init
• s/them/Vim
• s/whose/who's (grammatical error)

Make spoken terms resemble written terms

Try to make the captions mirror the idioms used in code. That means following the punctuation and capitalization styles for the programming language. For example, the Haskell expression Set.map might read "set dot map" if transcribed verbatim. We'd prefer to have the caption read "Set.map", to reflect the way it's written in code.

Suppose that the guest in the video writes this method:

def terminal_count
  leaf_count depth: MAX_DEPTH
end

If they were to dictate the body of that method, the captions might look like this:

leaf count depth is max depth

We'd prefer to have the captions follow how the code is written, like this:

leaf_count depth is MAX_DEPTH

To make corrections like this you have to follow what's happening in the screencast as well as reading the captions.

Example corrections:

• s/{append,add} child/{append,add}_child
• Turn 'method name' into method_name
• write file and directory names as they appear in the editor
• write the function and class names as they appear in the code

Discerning between inaudible and [inaudible]

With recorded speech it's sometimes hard to tell what the speaker is saying. Our transcriptionist uses the word inaudible as a placeholder for something that she couldn't make out. If you think that you can tell what the speaker is saying, please replace inaudible with what you hear. If you can't tell what the speaker is saying, please change inaudible to [inaudible]. If the speaker is actually saying the word 'inaudible', then just leave it unchanged!

Example corrections:

• s/inaudible/closing brace
• s/inaudible/and then mutating it to add them
• s/inaudible/[inaudible]

Captions should not be 100% verbatim

The dialogue in Peer to Peer videos is ad lib (i.e. not scripted). As you'd expect, it contains all sorts of mistakes, crutch words, and false starts. If we transcribed everything exactly as it was spoken then it would make for unpleasant reading. We want our captions to clearly communicate the speaker's intent, and we can get more clarity by leaving certain words out. Accuracy is important, but clarity takes precedence.

Our transcriptionist has a good ear for what's relevant and what's not. You'll notice that the captions aren't always 100% verbatim, and that's ok! We don't want our technical reviewers adding back in those words that our transcriptionist carefully omitted. Focus your attention instead on the technical language that our transcriptionist may have misheard.

Making a correction

As you watch the video pay close attention to the captions. When you notice a mistake in the captions text, follow these steps to make a correction:

• pause the video
• take a note of the video timestamp where you noticed the mistake
• open the .srt file in a text editor
• navigate to the caption containing the mistake
• correct the text (try to avoid changing timestamps or caption numbers)
• save the file
• commit the change into git, briefly describing the correction

Formatting the SubRip Text file

When modifying the .srt file, try to follow these constraints:

• caption text should not exceed 42 characters per line (important!)
• captions should be separated by one blank line
• there should be no trailing whitespace at the end of a line

Sometimes you'll replace the word inaudible with a long phrase of text (example). Try to break the caption text into two or more lines, each containing no more than 42 characters. Our transcriptionist will review your changes and fix any formatting errors that you introduce, but you can make it easy for them by sticking to these guidelines.

(Our transcriptionist also follows guidelines on how long a caption should be visible for. You don't need to understand these constraints, but if you're curious you can check out the Peer to Peer captioning style-guide.)

Please modify the formatting of a caption only if you have changed its content. If you change the formatting of a caption whose content is otherwise correct, it adds noise to the diff and makes it harder to review your corrections (see this commit for example).

Submit your changes as a pull request

When you've finished reviewing the portion of video you were assigned, you can submit your changes as a pull request.