A useful demo runbook lets a stranger reach one meaningful result without asking you for help. Start with the easiest access method you can keep working, then document the starting state, exact inputs, expected outcomes, reset steps and limitations.
Treat the runbook as part of the portfolio project: it shows how you make software understandable and testable. A polished interface helps, but a reviewer also needs to know whether a surprising result is a defect, a deliberate limitation or simply a different starting state.
Choose a hosted browser demo when the main feature is safe to expose and you can maintain the deployment. It gives a reviewer the shortest route to an interactive result, but someone must check that the service still runs, manage dependencies and decide what happens to data entered by visitors.
A local demo gives the reviewer more control and can avoid operating a public service, but setup creates friction. A walkthrough video or screenshots are easier to preserve and can work when interactive access is impractical; they cannot show how the application responds to a new input. You can offer a recording as a fallback even when the live version is your primary choice.
For a job application, select the version that best demonstrates the skill relevant to the role. If the interface is the point, a short browser flow may be appropriate. If architecture or testing is central, pair the flow with a concise explanation of the underlying choices. Readers exploring remote technology roles can use Talyca career resources to consider how portfolio evidence fits alongside the skills and hiring stages described for those roles.
Option | Reviewer effort | Maintenance and privacy trade-off
Hosted interactive demo | Open and follow a short flow | Maintain the deployment; prevent visitors from exposing sensitive information
Local demo | Install prerequisites and start the application | Less public hosting to maintain, but setup and version differences can obstruct review
Recorded walkthrough | Watch a fixed sequence | Easy to revisit, but cannot respond to the reviewer's own inputs
Screenshots with notes | Inspect selected states | Low access friction, but transitions and behavior remain untested
Put a short orientation at the top: the problem, the feature to try, the approximate number of steps and what the reviewer should see at the end. State whether the demo requires a particular browser, a network connection, an account, installation or a fresh session. List only prerequisites you have checked; if a browser is untested, say so rather than implying compatibility.
Describe the starting state in observable terms. For example, tell the reviewer whether a sample list should already contain two items or whether it should be empty. If a demo can retain previous changes, explain how to return to the starting state before beginning. A reviewer should not have to guess whether old data belongs to your example.
Provide sample inputs directly in the runbook, with labels that match the interface. Tell the reviewer what to click and what should change after each meaningful action. Prefer “the list shows one matching card” to “the filter works.” Include what to do if the expected state does not appear, such as resetting the demo or using the recorded fallback.
The following is a fictional example for an imaginary browser application called Task Shelf. Its behavior and sample data illustrate a runbook; they are not claims about an existing product.
Purpose: show how a user filters a small task list and marks a task complete. Prerequisites: a current browser and an internet connection. No account is needed in this example. Start on the Tasks screen, where two fictional cards appear: “Draft project brief” with status Open and “Review color palette” with status Done.
Step 1: select the Open filter. Expected result: only “Draft project brief” remains visible, and its status reads Open. Step 2: open that card and choose Mark done. Expected result: the card no longer appears while the Open filter is active. Step 3: select All. Expected result: both cards appear, and “Draft project brief” now reads Done.
Reset: choose Reset sample data, confirm the action and return to the Tasks screen. Expected result: the two original cards return with their original statuses. If they do not, reload the page once; if the initial state is still unavailable, use the walkthrough recording and note that the interactive demo could not be reset.
Known limits: this fictional version uses sample tasks, does not send notifications and does not demonstrate collaboration. Changes are intended for demonstration only. Do not enter personal information. If the actual implementation stores changes between visits or shares them between visitors, the real runbook must say so explicitly and explain the consequences.
Use invented sample records and labels, not customer exports, personal email addresses or production data. Never publish real credentials, API keys, access tokens or passwords in the runbook, repository, screenshots, recordings or demo interface. An account advertised as a demo account can still grant real access, so do not assume that a familiar-looking username and password are harmless.
If the application needs a secret behind the scenes, keep it out of published material and restrict what it can access. OWASP recommends managing secrets separately and limiting their scope. Also inspect logs and diagnostic output: OWASP warns against printing secrets there. Secret scanning can help identify exposed credentials, but it is a supplementary check rather than a reason to include them in the first place.
Be equally careful with artifacts offered as a fallback. A screen recording can reveal browser tabs or account details; a diagnostic trace may contain screenshots, network requests and response data. Playwright's documentation describes these trace contents, so review any trace before sharing it. If a real credential is exposed, remove the exposure and promptly revoke or rotate the credential; deleting visible text alone does not make the old credential safe.
Work through the instructions from the reviewer's perspective in a fresh session. Follow only the published steps, enter the exact sample values and compare each result with the stated outcome. Check the reset after making a change, then run the same sequence again. If another person can review the instructions, ask where they hesitated rather than explaining the missing step aloud.
Check the demo again after a deployment or a change to its sample data. A button rename, an expired service or a different default filter can invalidate otherwise clear instructions. Give the runbook a date you actually checked it and a way to reach you if the demo is unavailable. If you cannot keep the live version available, replace the primary route with a maintained recording and say that interactivity is unavailable.
Use this compact worksheet for one feature before expanding it. Replace each prompt with an observable answer, and remove any step that is not needed to reach the result.
Runbook field | Write down
Goal | The feature and the result the reviewer will observe
Access and prerequisites | How to open it; browser, connection, account or installation requirements
Starting state | What should already be visible and how to restore it
Inputs and actions | Exact fictional values, control names and sequence
Expected outcomes | Visible result after each meaningful action
Reset and fallback | How to repeat the flow and what to use if it fails
Limits and data | What is simulated, where inputs go and what visitors should not enter
Maintenance | Last actual check date and a contact route for a broken demo
Pick one portfolio feature and write a runbook for a single successful path. Test it from a fresh session, reset it, and ask someone unfamiliar with the project to follow it without coaching. Fix the first point of confusion they encounter, then add a fallback and known limits before sharing the portfolio.