How to write lab instructions students can follow

Before writing a single step, write one sentence that says what students will have when the lab is done: "a web page with your name on it, open in your browser", "a spreadsheet that totals each month", "a commit in your repository". That sentence goes at the top of the lab, and it tells you which steps belong. A step that doesn't move students toward it is background, and background goes somewhere else.

Keep the background short and separate from the steps. Durham University's guidance on laboratory guides asks for exactly that: a clear statement of purpose at the start, and background kept apart from the procedure, in its own box or under its own heading. Students who want the why can read it; students working through the steps don't have to wade through it to find the next action.

List what students need before step 1: the files, the accounts, the software and its version, the folder to work in. A missing file discovered at step 6 stops the whole lab.

A step is one thing the student does. "Create a file called index.html, add a heading and open it in the browser" is three steps, and the student who gets the second one wrong won't know which of the three went wrong. Microsoft's writing style guide puts the rule plainly: use a numbered list, and a separate step for each instruction. It allows one exception that works in labs too: two short actions in the same place can share a step.

Three habits make each step easy to follow:

• Say where before what. "In the folder my-page, create a file called index.html." The student looks in the right place before they act.
• Start with the verb. Open, type, paste, save, run. A step that starts with a verb reads as something to do; a step that starts with an explanation reads as something to skip.
• Be exact. Write the file name, the command and the value as the student must type them, in a code block they can copy. "Give the file a suitable name" leaves twenty students with twenty names, and your next step only works for one of them.

Expect students to start before they have read to the end. Durham's guidance warns about exactly this: not all students read all of the instructions before beginning. So nothing important can wait at the bottom of the page. If step 4 overwrites the file from step 2, say so in step 4, not in a note under the last step.

This is the part most lab sheets leave out, and it is the one that matters most. After an action, tell the student what the screen looks like when it worked:

1. In your editor, create a file in your my-page folder and save it as index.html.

   You should see index.html in the folder, not index.html.txt.

2. Double-click index.html.

   You should see your browser open with your heading in big letters.

The "you should see" line turns every step into a check the student runs alone. Without it, a student whose editor saved index.html.txt carries on for three more steps, and the problem shows up as something else entirely. With it, they notice at the step where it happened.

Durham's guidance makes the same point for laboratory work: tell less experienced students what should happen at each stage. Make it something they can see, not something they have to judge: a name, a number, the words on a screen, a colour. "It should work" is not a result. "The terminal prints Tests passed: 3" is.

A step that says what students should see will sometimes be wrong for some of them, and they need to know what to do next. Under each step where it happens, add the two or three ways it usually goes wrong and the fix for each:

Doesn't match?

• The browser shows <h1> as text: the file was saved as index.html.txt. Save it again and pick "All files" as the type.
• The editor opens instead of the browser: right-click the file and choose Open with, then your browser.

This is not just kindness. Lazonder and van der Meij tested two versions of a tutorial manual for novices: one with plenty of information about recognising, diagnosing and fixing mistakes, one with almost none. Learners with the error information trained faster and fixed mistakes better afterwards, and learned the task itself just as well. Writing down the usual mistakes costs you a few lines and saves the class the time it would spend waiting for you.

You already know the usual mistakes: they are the questions you answered last time. If you have never taught the lab, run it yourself on a clean machine, and watch someone else follow it without your help. Every place they hesitate needs a "you should see" line or a "doesn't match" entry.

End the list with what to do when none of it helps: "Still stuck? Raise the red card", or whatever your help signal is. A student who has tried the listed fixes asks with more to say, which makes the help quicker. Running a help queue covers the rest.

The first lab of a course needs every click written out. By the fourth, students who have opened a terminal a dozen times don't need "click the Start menu, type Terminal, press Enter" again, and reading it slows them down. Carleton College's guidance on lab handouts calls this scaffolding: make the first set of instructions the most detailed, and let later sections rely on what students have learned.

The same goes for one lab. Write out the first use of a new tool step by step; the second time, "Commit your change as before" is enough. What should not fade is the "you should see" line: experienced students still benefit from knowing the result they are aiming for.

Keep the format the same across every lab, too. Durham's guidance recommends a standard format for all lab guides, so students learn where to look: the goal at the top, steps numbered, results in bold, fixes in the same place each time.

Read your lab as a student would, and you will read what you meant, not what you wrote. The only reliable test is someone else following it with no help from you: a colleague, a teaching assistant, last year's student. Sit next to them, say nothing, and write down every place they pause, guess or ask. The Carpentries' lesson-development training gives the same advice for anyone writing lessons for others to teach or learn alone: if in doubt, be explicit.

Then teach it, and note where the class got stuck. That list is your next version.

In Workshopy a lesson is a list of steps that students follow on their own screens while you watch the room. Each # heading starts a step, so a lab written the way this guide describes, one goal per step, actions numbered inside it, maps onto it directly (writing a workshop in Markdown has the format). Code blocks get a copy button, so students paste the exact command instead of retyping it from a projector.

End a step with a Check your work block, and the "you should see" line becomes something the student pastes and Workshopy checks. You write the answer and the mistakes you expect; students never get either:

```check
What does the tab at the top of your browser say?

answer: index.html

mistake: .txt → The file was saved as text. Save it again as index.html, with "All files" as the type.
hint: Look at the top edge of the browser window, above the address bar.
```

A paste that matches a mistake you foresaw gets your words for it on the spot, right under the box, and after a wrong try Show a hint opens the next of your hints. A right paste marks the step done.

On your screen, beside the step, you see how many students passed, every wrong paste grouped, and which of them you foresaw; the room marks who pressed Done without checking. A wrong paste nobody foresaw is a new "doesn't match" entry for next time. A teacher block in the step holds your own notes, such as the usual slip and how long the step takes; students never get it.

A student whose problem isn't on your list presses Need help, picks a reason and can say what they see, and keeps working while the request waits in your Help tab, oldest first. If a step's instructions turn out to be wrong mid-class, edit the step and every student's screen updates. After the class, the report shows which steps had the most help requests and each check's wrong pastes: the steps to rewrite first.