Quizzer - cdig/docs GitHub Wiki

Disclaimer: A lot of Quizzer content was created before these standards. Going forward we'll hopefully get around to fixing it up, but there is currently content that doesn't conform. We know. Don't @ us.

Note: These are Quizzer-specific standards, that build on the Writing Standards. Be sure to follow those too when writing questions.

Creating Questions

Philosophy

Remember, we're always, always trying to test on knowledge. Questions should never be intentionally tricky because of sneaky wording or the question mechanics.

We should only create questions based on (or synthesized from) material covered in the lessons. To put it another way, we do not want to create questions based on material that is only introduced in puzzles, simulations, videos, etc. There are a few reasons for this. One is accessibility: lessons are more usable by people with blindness or low vision, motor skill difficulties, and non-native English speakers. Another reason is that are cultural expectations around the test that differ from how we design our quizzes. Our quizzes are low-stakes and, what's more, useful as a learning tool. That's not what people will expect, and we don't (yet) do a good job communicating how our quizzes are different. If someone takes a quiz and sees something they haven't seen before (eg: because it was introduced in a Match or Miss puzzle and they never happened to randomly encounter that thing), it can be a very emotionally difficult experience. So we need to be careful about using the quizzes in ways that might be frustrating or defeating to learners.

Select Multiple Answers

If answers are "A", "B", "C", etc, (we do this a lot on images—e.g. "Which letter indicates a relief valve?".), list the answers alphabetically & don't let them shuffle, so that A will come first. Same if there are numbers that seem to suggest a sequence.

  • Help the learner out by not making them hunt for the answer they want.
  • "suggest a sequence" is a judgment call. Listing the numbers 1-5 would absolutely be a sequence, but a bunch of values that don't directly follow each other is a gray area. I (Robyn) would probably still not shuffle a list like "125 psi, 205 psi, 430 psi, 670 psi", but you could make that argument and get away with it. I'm not dying on that hill.

True or False

True or false? (the question) is already implied by the two answers, True and False. Don't repeat it in the prompt.

A true or false prompt is a statement, not a question, so there should not be a question mark at the end of the statement. (If you have a valid exception to this blanket ruling, tell me about it 'cause I am curious.)

E.g. Don't write "The ball is red?" as the prompt. State it, and let the student judge it. "The ball is red." is the correct prompt.

Try for the plainest statement possible. Avoid double negatives, and regard even single negatives with suspicion. (Don't take a positive statement and just throw in a "not" to make it negative. Write the statement in a positive way instead.)

E.g.: Instead of writing, "The ball is not red." (negative statement), write "The ball is purple." (positive statement)

Quizzer automatically recognizes "True" and "False" answers, and does not shuffle them.

Formatting

Simple inline html like <b> is available for questions and answers, but make sure that formatting is never vital. It may not be included in translations to other languages, so don't use it in a way that's essential to the question.

Images

Quizzer images live in S3 under: lunchboxsessions/content/quizzer/[subfolder]

Images should always be optimized with ImageOptim before uploading to S3. SVGs are preferred if you're working with vector material.

SVGs should NOT be given extra whitespace to control for sizing anymore. Now we can & should do that directly in the question. (Link to aspect ratio calculator that Robyn likes)

All image names should be versioned, like image-name.1.jpg. If you need to change the image, change the version number. This is required due to server-side caching.

  • Because of this, you can't just upload a new image to the correct place on S3 and call it a day. You'll need to update the image path in the question (or questions, plural) to use the new image.

To get the S3 path, after you have uploaded the image, right-click on it in the S3 directory and choose "Copy Path". Paste this directly into the Image S3 Path blank.

Specify the width and height to display the image at. Do this even if the image displays correctly without that info. LBS has some limits - if you specify 3000 px width, you won't get it. But you can use this to tweak the image size without having to re-upload.

  • If you're working in illustrator, get the svg size from the artboard drop-down, in Artboard Options.
  • If you're working in Animate, it's probably the stage size.

Changes & Updates

If you update an image, clean up after yourself by deleting the old image from S3.

  • Images are slowly moving into folders. If you happen to change an image that's in the main directory (quizzer-images), put the new version into the appropriate folder. (Create one if it doesn't exist already. This should be the name of the session test the question belongs to.) One day, we'll be organized!

If you materially change a question, change the "X Takes Since" date to tomorrow. This resets the stats for that question. I'm a nerd about this so please help me see how each question is doing by resetting this when appropriate.

Warp Whistle Locations

Just kidding. But there are some cool hidden/non-obvious features that are pretty helpful.

Print All Questions With Images

The Print All page will show all questions that include images, with printer-friendly CSS. You'll also see a black frame and a red frame around each image.

  • The black outline surrounds the actual image. This is most useful in showing you if there has been whitespace included in the image that should be removed. It will also show you if the size specified is wildly wrong for the image (eg: too large, wrong aspect). Sometimes, an SVG might not appear (the black frame will just be a tiny square) — this is fine, it just means the SVG doesn't include the optional width & height properties (in CSS terms: it doesn't have an intrinsic size).
  • The red outline indicates the size specified in LBS. It might be bigger, smaller, or the same size as the black outline. It's just info - what you do with it is up to you.
  • To edit a question, click on the text of the question.

Preview All

The Preview All page will show ALL of the questions, as they would appear in a real test. Note that each question has a tiiiiiiiny edit link at top right of the text - very helpful! (Note: these links only appear for Chris, Crystal, Ivan, Nathan, and Robyn.) This is particularly awesome when combined with Find on Page, if you're looking for a particular question and also want to preview the image right away.

Tests Column

When looking at the Quizzer Questions table in LBS, the rightmost column shows the numbers of tests that a question is used within. This will help you find questions that are not used in any tests, or are used in (perhaps) too many tests.