Turn a Screenshot Portfolio Demo Into a Useful Plain-Text Companion
A useful plain-text companion lets a reviewer understand what your project was meant to do, how the demonstration was set up, what happened, and what remains unproven without relying on screenshots. Start with those facts, then describe the important actions and results in the order they occurred.
A caption such as “Dashboard after filtering” identifies an image, but it rarely tells the whole story of a multi-step demonstration. A companion can fill that gap while keeping the screenshots available for readers who want to examine the visual design.
What should the companion let a reviewer decide?
Give the reader enough information to judge the specific work you are presenting. For a practice project, that usually means the problem you chose, your contribution, the input used in the demo, the actions shown, and the observed output. Label the project as practice and distinguish a sample result from evidence of real-world use.
Imagine an applicant demonstrating a small task-list interface. Three screenshots show an initial list, a filter selection, and a shorter list. The relevant story is not simply that the screens look different: the applicant wants to show that selecting a status changes which sample tasks are displayed.
The companion should state the starting records and their statuses, name the control selected, and identify the records that remain visible. It should also say what the screenshots cannot establish, such as whether the filter works for every possible input or saves a choice between sessions.
Reader needs | Include in the text | Common gap to avoid
Purpose | The problem and the behavior being demonstrated | Naming the project without explaining its goal
Setup | Relevant sample data, starting state and environment | Assuming the reader can see the initial screen
Steps | Actions in sequence, using the visible control names | Jumping directly from the first screen to the last
Observed result | Specific output or changed state shown in the demo | Calling the project successful without describing what happened
Limitations | What was not shown, tested or implemented | Presenting a narrow demonstration as proof of complete reliability
When is a caption enough, and when do you need more?
Use a short caption to identify a screenshot and orient the reader: “Task list after selecting Open.” That may be sufficient as a label when the surrounding text already explains the meaningful information. If the image carries the explanation, however, the caption leaves the reader to infer the input, action and result.
The World Wide Web Consortium’s Web Accessibility Initiative explains that WCAG 2.2 Success Criterion 1.1.1 generally calls for a text alternative that serves an equivalent purpose for non-text content, with specified exceptions. Its guidance on complex images describes a short identification paired with a longer description when the information cannot be conveyed in a short phrase.
For a portfolio sequence, a practical approach is to identify each screenshot briefly and put the full walkthrough in nearby readable text. The walkthrough is a companion to the sequence; it does not by itself establish that an entire portfolio meets WCAG. Check the actual page, its controls and its other content separately.
What does a before-and-after example look like?
Before: “Screenshot 3: The filtered task dashboard.” This tells the reader which image is being discussed, but not what was filtered, how the filter was applied or what changed.
After, in a fictional plain-text companion: “Purpose: This practice project explores a task list that can be filtered by status. Setup: The demonstration starts with three sample tasks: Draft outline and Review notes are marked Open; Send summary is marked Done. Steps: In the status filter, I select Open. Observed result: The list shows Draft outline and Review notes; Send summary is no longer displayed. The screen also shows a count of two tasks. Limitations: This demonstration uses three sample records. It does not show whether the selection persists after a refresh or how the interface behaves with a large list.”
That example gives a reviewer a small, checkable chain: starting state, action and resulting state. It does not claim a business outcome, a user test or a performance result. If the screenshot does not actually show the count, remove that sentence; the description should follow the evidence rather than improve it.
A longer description has a cost: readers must spend more time with it. Keep the main path concise and move details that do not affect the demonstrated decision into a separate note. Describe color, position or layout when those features carry meaning, such as a status communicated only by color; skip a decorative background that plays no role in the result.
How do you write the walkthrough from your own screenshots?
First, write a one-sentence purpose that names the behavior you intend to show. Then inventory the screenshots in order. For each one, note the relevant on-screen text, selected controls, sample inputs and visible outputs. Do not assume that two adjacent images prove every action between them; add an action only when you know it occurred.
Next, write the setup before the first action. Identify the data and starting state that make the result understandable. Include the software or environment when it affects interpretation, but leave out incidental details that do not help someone follow the example. Use sample or anonymized data where appropriate, and check screenshots and text for personal information before sharing.
Describe each action and its immediate result in sequence. Use the interface’s actual labels so a reader can connect the text to the images. If a control changes several things at once, explain each meaningful change. If a result is an error, report the error and what you did next instead of editing the narrative into an uninterrupted success.
Finally, add a limitations note. Separate what you observed from what you intended to build, and say whether the demonstration omits setup, validation, persistence or other relevant behavior. If you contributed only part of a group project, identify your contribution accurately. A reader can then assess your work without having to guess where your responsibility begins or ends.
Where should the text live?
Place the companion close to the screenshots or provide a clearly labeled route to it from the demo. If it is a separate document, give it the same project name and make the relationship obvious. A reviewer who receives only the text should still see the project title, purpose and sequence; a reviewer on the visual page should be able to find the fuller description without searching for it.
For a web page, short image alternatives and a visible longer description can work together. The W3C complex-images tutorial shows approaches including an adjacent link to a long description and a description presented in the main content. Choose a presentation that suits the page, then check that the description is reachable and that the reading order makes sense.
When preparing an application, the broader context also matters: Talyca portfolio preparation resources connects this sample to guidance on written applications and sharing work for remote roles. Tailor the surrounding application to the role, while keeping the project description factual and understandable on its own.
What should a reviewer check before you submit?
Read the companion without looking at the images. Can you identify the project’s purpose, the starting state, each important action and the observed result? Then compare it with the screenshots: check labels, numbers, order and any visual relationship that matters. Resolve contradictions rather than asking the reader to decide which version is correct.
Check that the text can be selected and read as text, that its location is clear, and that any separate document opens in the format you intend to submit. If possible, ask someone unfamiliar with the project to describe what happened using only the companion. Their questions can reveal missing setup or an unexplained jump.
Finish by checking the limits of every claim. Mark hypothetical data as sample data, identify untested behavior and remove unsupported outcome claims. Update the companion whenever the screenshots or interface change; an accessible description that refers to an old version can mislead as readily as an absent one.