Parsons Practice Teacher Guide

Overview

Choose the workflow that matches your access

Both workflows use the same Parsons JSON format. Most teachers should share a tested file through their LMS. Publishing a problem set in the built-in menus requires access to the Parsons web server.

Recommended for most teachers

Create a problem set with AI—no programming required

You do not need to write code or understand JSON syntax. The AI problem prompt tells an AI assistant how to turn your trusted lesson materials and sample algorithms into a Parsons Practice data file.

1. Gather the source material students should practice, such as lesson notes, standards, algorithm descriptions, pseudocode, or Java examples.
2. Go to Generate Parsons problems with AI and select Copy prompt.
3. Paste the prompt into your preferred AI assistant.
4. Replace the bracketed course, unit, standards, title, grade level, problem count, session options, weekly goal, language, and code-scope settings.
5. Paste your source material between SOURCE MATERIAL BEGINS BELOW and SOURCE MATERIAL ENDS HERE, then submit the prompt.
6. After the AI creates the set, ask it: “Save this as a downloadable JSON file named course-unit-topic-parsons.json.”
7. Download the resulting .json file. Do not change its ending to .txt, .docx, or .pdf.
8. Open and test the file in Parsons Practice before sharing it with students.

Instructional design

How Parsons Practice works

A Parsons problem gives students the needed code lines in mixed order. Students drag or move those code cards into a solution area, arrange them into the correct algorithm, and select Check answer.

The tool compares the student's submitted line IDs to the correct ordered line IDs in the JSON file. If the order is correct, the problem is marked solved. If it is incomplete, out of order, or contains a distractor, students receive feedback and can try again.

This format supports both AP Computer Science Principles pseudocode and AP Computer Science A Java. Students can focus on sequencing, expressions, selection, iteration, methods, objects, and program behavior while still practicing the notation or syntax used in their course.

AI-assisted authoring

Generate Parsons problems with AI

Replace the bracketed settings, paste your source material or algorithm descriptions at the bottom, and submit the entire prompt to an AI assistant. Review every problem for accuracy before publishing the JSON file.

You are creating a JSON Parsons-problem data set for the Parsons Practice website.

COURSE: [ENTER COURSE NAME]
UNIT: [ENTER UNIT, CHAPTER, STANDARD, OR SKILL]
STANDARDS: [ENTER THE STANDARDS THAT MAY BE ASSESSED]
PROBLEM SET TITLE (PAGE H1): [ENTER THE TITLE SHOWN ABOVE THE PROBLEMS]
DATA SET MENU LABEL (MANIFEST): [ENTER A SHORT LABEL, SUCH AS 1.1-1.3]
TARGET GRADE OR COURSE LEVEL: [ENTER LEVEL]
APPROXIMATE NUMBER OF PROBLEMS: [ENTER NUMBER, USUALLY 5-15]
SESSION SIZE: [OPTIONAL: NUMBER OF RANDOM PROBLEMS PER SESSION, OR NONE]
BALANCED SESSION GROUPS: [OPTIONAL: LIST EACH GROUP ID AND NUMBER TO SELECT, OR NONE]
WEEKLY GOAL: [OPTIONAL: ENTER REQUIRED SESSIONS PER WEEK AND MINIMUM MINUTES PER SESSION, OR NONE]
PROGRAMMING LANGUAGE: [AP CSP PSEUDOCODE OR JAVA]
CODE SCOPE: [STATEMENTS, CODE SEGMENT, OR COMPLETE PROGRAM]
SPECIAL REQUIREMENTS: [OPTIONAL: FOR EXAMPLE, CREATE-TASK-STYLE PROCEDURES OR ONE PROBLEM FROM EACH ALGORITHM FAMILY]

TASK
Convert only the source material pasted below into high-quality Parsons problems. A Parsons problem gives students mixed-up code cards that must be arranged into the correct algorithm.

TITLE RULES
1. Use PROBLEM SET TITLE as the top-level "title" in the problem-set JSON. This becomes the H1 heading above the problems.
2. DATA SET MENU LABEL is a separate short label for the problem-set entry in data/problem-sets.json. It is not a property in the problem-set JSON.
3. Do not replace the page H1 title with the shorter menu label.

CONTENT RULES
1. Use only facts, skills, algorithms, and concepts supported by the supplied source material. Do not invent missing course content.
2. Select the most instructionally important algorithm patterns rather than converting every sentence.
3. Each problem must have one clear algorithmic goal.
4. Follow the selected programming language exactly.
5. For AP CSP Pseudocode, use course notation such as:
   - variable ← expression
   - INPUT()
   - DISPLAY(value)
   - IF(condition)
   - ELSE
   - REPEAT n TIMES
   - REPEAT UNTIL(condition)
   - FOR EACH item IN list
   - PROCEDURE name(parameter)
   - RETURN(value)
   - MOD for remainders
   - lists use 1-based indexing
   - LENGTH(list), APPEND(list, value), INSERT(list, index, value), and REMOVE(list, index)
   - RANDOM(a, b), where both integer endpoints are inclusive
6. In AP CSP Pseudocode, use the "indent" field to show block structure. Do not add standalone brace cards unless the supplied source explicitly requires braces.
7. For AP CSP robot problems, use only the operations and relative directions supported by the supplied course reference. If only ROTATE_LEFT() is permitted, construct a right turn with three left rotations.
8. For Java, preserve correct capitalization, declared types, semicolons, parentheses, braces, operators, and method calls.
9. Follow the selected code scope. A statement or code-segment problem may omit surrounding class or method boilerplate only when the prompt supplies every variable, object, method, input, and precondition students need. A complete Java program must include all code needed to compile.
10. Make every prompt self-contained. State initial values, existing variables or lists, 1-based indexing, sorted-list requirements, expected output, and robot starting conditions whenever they affect the unique solution.
11. Keep each code line short enough to fit on a draggable card.
12. Put the correct solution lines in the "lines" array in the one exact order accepted by the app. Avoid problems with multiple equally correct line orders unless dependencies make the intended order unambiguous.
13. Add "indent": 1 for one level of block nesting, "indent": 2 for two levels, and "indent": 3 for three levels. Omit indent when it is 0.
14. For Java, make the placement of opening and closing braces unambiguous and consistent within each problem.
15. Include 0-2 useful distractor lines per problem when they reveal a likely misconception. Distractors must go in the "distractors" array, not the "lines" array and must never be required by the correct solution.
16. Add specific feedback to each distractor explaining why it is not part of the correct solution.
17. Add 1-3 useful topic tags to every problem.
18. Add a "standard" property to every problem. Use the most specific supplied standard that accurately matches that problem.
19. If SPECIAL REQUIREMENTS asks for a Create-task-style procedure, the procedure must have a student-developed name, at least one parameter used in the algorithm, sequencing, selection, and iteration inside the procedure. Include a meaningful call with argument values and use or display the returned result when the procedure returns a value.
20. Avoid duplicate or nearly duplicate problems.
21. If the source is insufficient for the requested number of problems, create fewer problems instead of inventing content.

SESSION RULES
1. Use only one session-selection method: either "sessionSize" or "sessionGroups", never both.
2. If SESSION SIZE gives a number and BALANCED SESSION GROUPS is NONE, include top-level "sessionSize". It must be a positive integer no larger than the number of problems.
3. If BALANCED SESSION GROUPS are provided, omit "sessionSize". Add top-level "sessionGroups", with a unique lowercase-hyphenated "id" and positive "count" for every group. Add a matching "sessionGroup" value to every problem intended for that group.
4. Each group must contain at least as many problems as its requested count. The total selected per session is the sum of the group counts.
5. If both SESSION SIZE and BALANCED SESSION GROUPS are NONE, omit both properties and the app will use the complete problem set.
6. If WEEKLY GOAL gives specific requirements, include a top-level "goal" object with "sessionsPerWeek", "minimumMinutes", and an optional "note". If WEEKLY GOAL is NONE, omit "goal".

ID RULES
1. Create a unique problem-set "id" using lowercase letters, numbers, and hyphens, ending in "-v1".
2. Create a unique, descriptive problem "id" for every problem using lowercase letters, numbers, and hyphens.
3. Create a unique, descriptive line "id" for every line and distractor using lowercase letters, numbers, and hyphens.
4. IDs must describe the concept, not the position. Use "sum-list-loop", not "line-1".
5. Do not reuse an ID within the problem set.

OUTPUT RULES
1. Return one valid JSON object and nothing else.
2. Do not use Markdown code fences.
3. Do not include commentary before or after the JSON.
4. Use double quotation marks around all property names and text values.
5. Escape quotation marks inside code strings, such as DISPLAY(\"Passing\") or System.out.println(\"Passing\");.
6. Do not include trailing commas.
7. Use the appropriate top-level structure. This example uses a random session size and weekly goal. Omit "sessionSize" when using "sessionGroups":

{
  "id": "course-unit-parsons-v1",
  "title": "Student-Facing Problem Set Title",
  "course": "Course Name",
  "unit": "Unit Name",
  "language": "Programming Language or Notation",
  "description": "One-sentence description of the problem set.",
  "sessionSize": 10,
  "goal": {
    "sessionsPerWeek": 3,
    "minimumMinutes": 10,
    "note": "Complete three practice sessions this week."
  },
  "problems": [
    {
      "id": "unique-problem-id",
      "title": "Student-facing problem title",
      "standard": "Specific standard assessed by this problem",
      "prompt": "Arrange the lines to...",
      "goal": "Short explanation of the algorithmic target.",
      "tags": ["Topic", "Skill"],
      "lines": [
        { "id": "unique-line-id", "text": "code line" },
        { "id": "unique-indented-line-id", "text": "indented code line", "indent": 1 }
      ],
      "distractors": [
        {
          "id": "unique-distractor-id",
          "text": "plausible wrong code line",
          "indent": 1,
          "feedback": "Why this line is not correct."
        }
      ]
    }
  ]
}

When BALANCED SESSION GROUPS are requested, replace "sessionSize" with this form:

"sessionGroups": [
  { "id": "foundations", "count": 2 },
  { "id": "search", "count": 3 }
]

Then add the corresponding property to each grouped problem, for example:

"sessionGroup": "search"

FINAL QUALITY CHECK BEFORE RESPONDING
- Confirm that the JSON is syntactically valid.
- Confirm that the problem set has id, title, course, unit, language, description, and problems.
- Confirm that every problem has id, title, standard, prompt, tags, and lines.
- Confirm that every line has id and text.
- Confirm that all IDs are unique.
- Confirm that no line or distractor ID is reused within a problem.
- Confirm that correct answer lines are in the correct order.
- Confirm that distractors are not required for the correct answer.
- Confirm that each prompt provides enough context for one unambiguous solution.
- Confirm that every code line follows the selected programming language.
- For AP CSP Pseudocode, confirm that every solution follows the requested course notation.
- For Java complete programs, confirm that each correct solution compiles. For Java statements or code segments, confirm that each solution is valid in the context stated by the prompt.
- If sessionGroups are used, confirm that every group ID is unique, every count is positive, every grouped problem has a matching sessionGroup, and every group contains enough problems.
- If a weekly goal is supplied, confirm that its session and minute values are positive integers.
- Confirm that all claims and algorithms are supported by the source.
- Confirm that the output contains no Markdown or explanatory text.

SOURCE MATERIAL BEGINS BELOW
--------------------------------------------------
[PASTE LESSON NOTES, ALGORITHM DESCRIPTIONS, VOCABULARY, SAMPLE CODE, OR STANDARDS HERE]
--------------------------------------------------
SOURCE MATERIAL ENDS HERE

Manual workflow

Test the JSON file by opening it in Parsons Practice

Use the same manual process students will use. This confirms that the file is valid, the problem set opens, and every algorithm can be reconstructed from the prompt and supplied cards.

1. Save the AI output or hand-written set as a plain-text file ending in .json.
2. Open Parsons Practice through its web address and complete the learner setup with a clearly labeled test profile.
3. Under Current material, find Or open a problem data set and select the JSON file.
4. Confirm that the course, unit, title, description, language, session size, and problem count are correct.
5. Read each prompt without looking at the solution. Confirm that a student has enough context to determine the intended algorithm.
6. Solve every problem using only the required lines and select Check answer.
7. Add each distractor to a solution and confirm its feedback explains the misconception clearly.
8. For Java, compile and run complete programs and closely inspect code segments for types, braces, capitalization, punctuation, and required context.
9. Complete a session and download the practice screenshot. Confirm that its identifying information and statistics are correct.

Manual workflow

Share a problem set through Canvas or another LMS

The JSON file can be distributed like any other class attachment. Students need both the downloaded problem-set file and a link to Parsons Practice.

Recommended Canvas setup

1. Create a Canvas Assignment, Page, Announcement, or Module item for the practice activity.
2. Upload the tested .json file to Canvas Files or attach it directly to the item.
3. Add a clearly labeled link such as Download the Unit 2 Parsons problem set.
4. Add a second link to Parsons Practice.
5. Paste the student directions from the next section into the Canvas item.
6. If students must document practice, enable a file-upload submission and request the Parsons practice screenshot—not the JSON file.

Other ways to distribute the file

• Attach it to an assignment or post in another LMS.
• Share it through a school-managed cloud drive with download permission.
• Email it as an attachment when school policy permits.
• Place it in a shared class folder or on a teacher website.

Directions to give students

Download and open a teacher-provided problem set

You may copy and paste these directions into Canvas or another LMS.

Returning for another session

Use the same browser and device whenever possible. Parsons Practice remembers progress and an unfinished session in that browser. A manually opened set may need to be selected again after the page is refreshed or reopened; after reopening it, select Continue study session. You do not need another download if the original JSON file remains on the device.

Classroom routine

How students should use Parsons Practice

1. Enter their own first name, last name, and email.
2. Confirm that the correct course, unit, and problem data set are selected.
3. Read the problem standard, prompt, and goal before moving any code cards.
4. Drag or add needed lines into the solution area.
5. Use Up, Down, and Remove to refine the algorithm, especially on smaller screens.
6. Trace the algorithm from the beginning before checking the answer.
7. If they must stop early, select End session and later select Continue study session in the same browser.
8. After two completed sessions, copy the displayed difficult algorithm into a Coding Notebook when required.
9. Revise after feedback, then download a practice screenshot when requested.

From ordering to written code

Notebook Checkpoint after two sessions

Parsons Practice distinguishes an attempt from a completed session. Selecting Check answer records one attempt. A session is completed only after the student has checked every problem selected for that session at least once. After two completed sessions in the same problem set, the Notebook Checkpoint appears.

How the algorithm is selected

The app compares the student's cumulative problem-level history within the current data set. Incorrect attempts receive the greatest weight; repeated attempts and lower accuracy resolve close results. The checkpoint remains hidden when the student has not made an incorrect attempt because the app does not have evidence that one algorithm was more difficult than another.

What students see

• The difficult problem's title, goal, and standard
• Every required solution line in the correct order
• The intended indentation from the problem's indent fields
• A consistent Coding Notebook heading and direction for both Java and AP CSP pseudocode

For Java, the reminder emphasizes indentation, braces, capitalization, and punctuation. For AP CSP pseudocode, it emphasizes indentation, assignment arrows, block structure, and capitalization. Distractor lines are never included in the notebook algorithm.

Instructional rationale and intended benefit

Parsons problems reduce the burden of generating every line while students reason about sequence and structure. The notebook step intentionally changes the task after that supported practice: students reproduce one complete solution and then trace or annotate it. The hoped-for benefit is a bridge from recognition and rearrangement toward independent code production. Copying alone is not the goal; students should explain what important sections do, trace a sample execution, or identify the algorithmic pattern.

Writing the algorithm by hand may also provide additional motor, visual, and sensory cues. A 2025 peer-reviewed review describes broader neural engagement during handwriting and possible learning and memory benefits in some educational settings.¹ However, a 2025 scholarly commentary cautions that greater brain connectivity does not automatically demonstrate better learning in every task.²

Suggested classroom use

• Ask students to preserve the exact syntax or notation shown by the app.
• Require a margin trace, variable table, or short explanation beside the copied algorithm.
• Have students label the pattern, such as traversal, accumulator, search, selection, or method call.
• Use the notebook entry as a warm-up: cover it, reconstruct part of it, and then check the written version.

Research cited

1. Marano, Giuseppe, et al. “The Neuroscience Behind Writing: Handwriting vs. Typing—Who Wins the Battle?” Life 15, no. 3 (2025): 345.
2. Pinet, Svetlana, and Marieke Longcamp. “Commentary: Handwriting but Not Typewriting Leads to Widespread Brain Connectivity.” Frontiers in Psychology 15 (2025): 1517235.

Student data

Privacy and local storage

Parsons Practice stores the student profile, solved-problem history, attempts, submitted order, and practice time only in the browser's local storage. The app does not submit this information to a database or server.

The screenshot receipt is created on the student's device. Students share it only if they upload or submit the downloaded image through your normal classroom workflow.

Quality check

Test a new problem set

1. Open the JSON file in a validator or code editor and confirm there are no syntax errors.
2. Open Parsons Practice through a web server, not directly from Finder, so JSON files can load.
3. Select the problem set from the menu or use the direct ?set= URL.
4. Solve each problem once using only the listed correct lines.
5. Try at least one distractor and confirm the feedback is helpful.
6. Complete two full sessions with at least one incorrect attempt and confirm that the Notebook Checkpoint shows the correctly ordered algorithm and the Coding Notebook label.
7. Download a practice screenshot to confirm the receipt contains the expected class, title, date, and progress.