Writing a first-run experience that gets someone started

A first-run experience has a practical job: help a new person do something useful with the product. It is easy to replace that job with a tour. Five screens introduce features, a checklist asks for a profile photo and a welcome message promises a better way to work. The person still has to discover what to do first. A useful opening begins with an action that produces a result they can recognize, then supplies the information needed to take it.

This guide develops an illustrative first-run sequence for a tool that collects feedback on a draft. The new user wants a colleague to review one document. The useful result is a review request that reaches the right person with the correct version and a clear explanation of the decision needed. That gives the writer a concrete sequence to draft and test before polishing the welcome screen.

Choose one first result

Write a short definition of success for the opening session. In this example: “Create a review request for one draft and understand how to tell when feedback arrives.” That excludes a full team setup, a lesson on every permission level and a catalogue of advanced features. Those subjects can appear when the person needs them. The initial sequence needs to support the first request and the decisions that make it valid.

Ask what the person brings to the task. They may have a document ready, only a rough note or nothing suitable to upload yet. They may know the reviewer’s email address but be unsure whether the colleague needs an account. These starting conditions affect the first screen. A useful draft can offer a sample file for exploration while keeping the path to a real request obvious. The sample should be labeled so the person knows what is real.

Draft the sequence in plain text

Before designing the screens, write the sequence as a script. Start with “Create your first review request.” Follow it with “Add the draft you want reviewed,” “Choose who should review it,” and “Explain the feedback you need.” Then draft the review screen and the final action. Each step should have a purpose the writer can explain in one sentence. If a step exists only to complete a user profile, reconsider whether it belongs before this first result.

For the worked example, the request description might ask: “What should the reviewer focus on?” A short example can make the question tangible: “Check whether the proposal answers the client’s three questions.” That is more useful than a vague instruction to add context. It also encourages a request the recipient can act on. Keep the example visually distinct from entered content so nobody accidentally sends the sample as their own message.

Put necessary explanations beside decisions

The writer needs to know whether an invitation sends immediately or waits until the final review. Say this beside the invitation field. The user needs to know which version is being shared. Show the filename and a preview before the send action. If the recipient can comment but cannot change the original, make that permission clear in the review summary. These explanations earn their place because they answer questions raised by the current action.

Instructions should be accessible as well as short. A placeholder disappears when someone types, so it is a poor home for guidance they may need while entering information. W3C’s form-instruction guidance describes ways to provide help that is associated with the relevant control. For this example, keep the label and the short description available throughout the entry step. Test that connection with the input methods and assistive technology relevant to the product’s users.

Write the uncertain states

The normal sequence is only part of the draft. Write what happens when the file is too large, the upload stops or the address is incomplete. “Something went wrong” leaves the person with the burden of guessing. A useful message names what failed and gives the next available action. For an interrupted upload: “The file did not finish uploading. Choose the file again to retry.” The exact wording must match what the system actually knows.

Keep entered work where it is safe to do so. A person who corrects an email address should not have to rewrite the feedback request. If the system cannot preserve something, explain the consequence before asking them to proceed. W3C’s validation tutorial covers communicating input requirements and supporting corrections. A first-run copy review can use that guidance while checking each error against the actual behavior of the product.

Make the final action precise

At the review step, the person should see the document, recipient, requested feedback and access permission together. Label the action with the event it triggers, such as “Send review request.” A button saying “Continue” does not tell the person that an email will leave the system. If the product saves a draft first, label that separately. The action and its consequence should be understandable before the click.

The next screen needs an equally precise status. A request created in the product is different from a notification delivered to a recipient. Use the status the system can establish and give the user a route to the request record. The confirmation might show that the request is open, who it is addressed to and where feedback will appear. Avoid celebrating completion of the recipient’s job when the user has only started the exchange.

Give the second visit a place to begin

A first-run script should consider what happens after the browser closes. When the user returns, they need to find the request they just created. An empty dashboard with a second welcome message makes them start over mentally. Show the current request, its status and the next action available. If the reviewer has not responded, the interface can show the waiting state without implying that the user needs to create another request.

The email sequence should use the same names for the same things. If the product calls the item a “review request,” the notification should not call it a “campaign.” Consistency helps the person connect the message with the task they remember. Include a direct route to the relevant item and review what a signed-out user sees when they follow it. The return path is part of the first experience because it determines whether the initial work remains useful.

Test the draft before expanding it

Use a basic prototype with the actual script and ask a new participant to request feedback on a sample document. Let them read and act without a guided tour. Note where they hesitate, what they expect to happen and which explanations they skip. After the final action, ask them to find the request again. Then introduce an incomplete address or failed upload to see whether the recovery copy helps them continue.

Revise the script around observed problems. A feature that nobody needs to finish this task can wait for a later moment. An explanation that prevents the wrong file being shared belongs before the send action. End the review with a compact set of decisions: the first useful result, the steps that produce it, the evidence shown before commitment and the messages that support recovery. That gives the product team a first-run experience built around a real piece of work, ready to test again as the implementation takes shape.