Section author: ACF (webmaster@acf-quizbowl.com)

Finalization

The finalization process involves the following steps, to be performed sequentially. Do not skip any steps.

The finalization process can take anywhere from half a day to a few days, so make sure to allot more than enough time to accommodate the process.

The last step in the process, dissemination of packets to site hosts, should ideally take place no later than 24 hours before the first mirror.

Hard Deadline for Editing

It is recommended that the head editor implements a hard deadline on editing or proofreading the documents.

After this deadline, they themselves will handle resolution of outstanding comments/suggestions, regardless of whether the corresponding editor has responded or not.

Important

ACF strongly recommends that the absolute latest this deadline be set is 48 hours before the first mirror.

Tip

ACF suggests that the editing team try to aim for this deadline to be set one week before the first mirror.

It is acceptable to let this deadline slip by a few days if necessary, but it is best to aim for a more conservative deadline. The earlier this deadline the better.

Comment Resolution

All comments and suggestions across all packet documents should be resolved by editors.

Cross-Checks

Once all comments have been resolved, team members should do the following checks packet-by-packet, clearly stating their progress (e.g. “finished checking X for packet A-D”).

Tip

It is suggested that a #finalization channel be created in the server.

Then, three separate threads should be made for each bolded check task below, so that different members of the editing team can work on different sub-tasks in parallel.

  • Packets vs. Answerline Spreadsheet

    • Each question in the packet matches the placement and content of its corresponding cell on the answerline spreadsheet.

  • Question Authorship

    • Each question has the correct attribution to either the Editors or submitting team.

    • Each author tag on submitted questions matches the packet title.

    • Questions written by the editing team should be tagged as <Editors, Category>.

    • Questions edited from submissions should be tagged as <University X, Category>.

    • Tiebreaker tossups and extra bonuses edited from submissions should also be prefaced with DO NOT READ TO University X. inline.

      • Do not place this disclaimer on the previous line, because MODAQ will not parse it in the question if so.

  • Minor formatting

    • Every bonus part should have a difficulty modifier.

    • Front matter (All authors and editors should be listed.)

    • Post-question notes are formatted in complete sentences.

    • The number of quotation marks are even in every packet (if they’re odd then one is unmatched, which can break MODAQ).

    • Straight quotes are to be replaced by curly quotes.

    • No stray spaces or whitespace are bolded or underlined.

Locking

The packets should now be locked from editing by anyone except the head editor (and/or any ACF officers involved in production, e.g. the Webmaster).

Anyone else on the team should only be able to comment, not edit.

Formatting Scripts

The finalization Google script, qbFormattingTools.gs, is located at this GitHub Gist.

It should each be installed in the first packet in the Packets folder and then run from there. To install it:

  • Go to the first packet Google Doc in your Packets folder.

  • Click Extensions → Apps Script.

  • Click the plus sign next to Files on the left panel, and add a new script called qbFormattingTools.gs.

  • Paste in the raw script text from the Gist in the body.

  • Save the file.

  • Click the plus sign next to Services on the left panel and add the Google Docs API.

  • Close the Apps Script, and reload the packet Google Doc.

  • Wait for a second. A tab next to Help called QB Formatting Tools should appear. (You may need to reload a few times.)

  • Click QB Formatting Tools → Run (Finalize + Keep-with-next).

  • A pop-up will appear asking for permission to run. Accept.

  • Run again, and follow the prompts.

  • The PG formatter may prompt several times depending on how many packets you have.

The script performs two tasks:

Keep-With-Next

Auto-pads each packet in the Packets folder properly with page breaks so that questions don’t leak across pages. It takes a few minutes to run. Based on this script.

Pronunciation Guide Formatting

Auto-formats all pronunciation guides in the Packets folder properly, all in one go. It takes a few minutes to run. Based on this script.

“Eye Test” Verification

The editing team should briefly look over the packets to make sure the finalization scripts performed their tasks properly without breaking other aspects of the packets.

Conversion to JSONs

All packets, including the tiebreakers + extras packet, should be downloaded from Google Docs as Word documents (DOCXs).

The set of Word documents should then be converted to JSONs via either:

Generation of Tiebreakers + Extras

The tiebreaker tossups and extra bonuses should be generated as individual JSON files by splitting the tiebreakers + extras packet JSON via either:

After running the script, if you have a packet with 10 TB tossups and 5 extra bonuses you should have 10 TB tossup JSON files and 5 extra bonus JSON files.

MODAQ Verification

All the JSON packets should be tested via either:

Compression

Each set of DOCXs and JSONs should each be compressed into ZIP files, titled of the form 20XX-acf-set_json.zip/20XX-acf-set_docx.zip.

Each set of TB tossup JSONs and extra bonus JSONs should be compressed into their own ZIP files, titled of the form 20XX-acf-set_json-TB.zip/20XX-acf-set_docx-TB.zip. It’s suggested that you create the top-level ZIP of JSONs/DOCXs to contain the corresponding TB/extra set zip file, not the individual TB/extra JSONs/DOCXs.

Backup

In the production Google Drive’s Packets folder, create subfolders called DOCX and JSON. Upload each individual DOCX/JSON file, as well as the ZIP files, to their corresponding folder.

Dissemination

The ZIPs of JSONs and ZIP of DOCXs should then each be shared with all site hosts.