witr-radio/manuals

Our station's training manuals, typeset in LaTeX.

Manuals

This repository contains our organization's training manuals:

• All Member Manual — general information about the station that every member should know
• DJ Trainee Manual — a guide to help new DJs learn how to operate our equipment
• DJ Trainer Manual — a guide to help existing DJs train new ones

Motivation

We wanted to upgrade from exporting Word documents as PDFs, and one of our members volunteered to typeset the manuals in LaTeX. The manuals looked better, but some members were concerned about the sustainability of this project — not everybody knows how to use LaTeX.

To mitigate those concerns, we're publishing the manuals on GitHub and compiling them using TravisCI. We're also making sure to extensively comment the manuals as a reference for future maintainers who will need to dig through what's already here and make changes. By offloading the compilation to ‘The Cloud,’ we remove the largest stumbling block to using LaTeX: installing it. Internally documenting the manuals helps soften the second largest stumbling block to using LaTeX: learning how to use it.

Contributing

If you're part of WITR, please feel free to make a pull request with any updates to the manuals. Someone on the engineering staff will review and merge your PR.

If you're just a passer-by, we welcome your contributions too! Have you spotted a typo? Are you a fellow radio engineer who's noticed something inaccurate (legally or otherwise)? Do you want some way to justify your English degree? Drop us a PR, and we'll gladly consider your input.

manuals's Issues

Under/Overfull hboxes everywhere

The manuals are riddled with under/overfull hbox problems. We should really clean these up.

• amm
• trainee
• trainer

½ fraction in DJ Trainer Guide is typeset in CMS

The ½ fraction in the DJ Trainer Guide is typeset in Computer Modern Serif, not Century Gothic. This is incorrect.

The DJ training guide has no content

I just haven't done it yet. Will update when it's done.

All of the bulleted lists in the AMM are too close to the previous paragraph

The changes I made in witrman.cls to move the lists in the DJ training guide closer to their previous paragraphs seem to have wrecked other documents.

Potential solution: move that fix into a new macro, which can be selectively applied where necessary?

Fix split Homework boxes in DJ Trainer Guide

The DJ Trainer Guide has some issues where the bottom or top rule of a Homework section isn't on the same page as the rest of it. We need to figure out how to tell LaTeX not to split them apart.

Travis CI doesn't put the compiled manuals anywhere

I haven't configured Travis to publish the manuals anywhere yet, since I'm not sure how we want to do it. GitHub Pages seems promising, but I don't want to write another Jekyll theme, and I'm not sure how a Jekyll blog would even work for this. A new posting for every build?

Box diagrams in DJ Training Manual aren't TikZ

Right now, the box diagrams in the DJ Training manual are JPEGs that I scraped out of the original Word file. The manual would look much better if these were proper TikZ diagrams.