A terminal screenshot should show more than evidence that a command ran. A reader needs to see which command produced the output, which lines matter, and how the result connects to the instructions. A crop full of tiny text makes all three harder. Before adding any image, decide what it will help someone see: a visual detail, a relationship, an expected result, or a mistake to avoid.
That is a tougher test than asking whether an image looks good. In a Java setup guide, a screenshot might distinguish the project SDK from the language level in an IDE. In a Linux permissions guide, a small annotated example could connect owner, group, and other permissions to characters in a listing. A generic laptop photo cannot do either job. It may set a mood, but it should not displace an image that helps someone learn.
Start with the reader’s next decision
At each possible insertion point, ask what the reader needs to recognize or compare. Try writing the caption before choosing the image. If all you can say is “A developer working on a computer,” the image probably has no instructional purpose. “The project SDK is selected separately from the compiler’s language level” points to something specific worth showing.
Look for moments when a beginner has to connect the instructions to an interface or a result:
- Location: Which setting, file, or panel should the reader find?
- Comparison: How do the correct and incorrect states differ?
- Sequence: Does the order of steps affect the outcome?
- Structure: Would a diagram make the relationships between components clearer?
- Verification: What should appear after an authorized, safe step succeeds?
Not every answer needs an image. A two-line command and its output are often clearer as selectable text. Keep code as text so readers can copy it, inspect punctuation, and use assistive technology. Save screenshots for cases where the layout matters, rather than capturing text simply because it appeared on a screen.
Match the image type to the explanation
Screenshots for interface-dependent steps
Use a screenshot when readers need to pick out a control among similar ones. An IDE, for example, may have separate fields for a JDK installation, a project SDK, and a build target. Showing their positions makes a warning about mixing them up easier to understand. Capture the smallest area that still gives enough context: keep the panel title and field labels, but leave out unrelated toolbars and desktop background.
Interfaces change. Name the application and version in the surrounding text when they affect the instructions, and revisit screenshots when you update the article. If a control often moves, its label and purpose may be more useful than an arrow aimed at one spot. The written instruction must still work without the screenshot.
Diagrams for relationships and flows
For connections between parts, a diagram may work better than a screenshot. A simple flow showing a browser, a local development server, and an application log can explain where a request appears without suggesting that readers test systems they do not control. In a defensive networking lesson, a diagram can distinguish a machine’s local address, a router, and a permitted lab target more clearly than a crowded network utility window.
Include only the components needed for the point you are making. Label arrows by what they represent; if direction matters, use arrowheads and explain them in the text. Decorative lines leave readers guessing. Even an accurate ten-box diagram may be harder to follow than two smaller ones placed beside the sections they support.
Photos for physical or spatial details
Photos help when the subject has a physical form: a network port, the position of a hardware security key, or the difference between a cable label and a connector shape. They do less for abstract topics such as password-manager behavior or file permissions. A prepared example, interface crop, or diagram usually explains those better.
Choose a precise image instead of a plausible one
An image can look relevant and still teach the wrong thing. A stock terminal photo may display a command unrelated to the article; a security-themed graphic may contain invented warnings or unreadable code. Check everything visible, not just the main subject. A beginner may reasonably assume that a displayed command or configuration value is meant to be followed.
For tutorials, take screenshots in a controlled environment that matches the steps you describe. Use a small test project or local lab rather than a production system. Check that filenames, paths, software versions, and output agree with the prose. If you show a failed command, label it as a failure and explain why it failed; do not leave an error looking like the expected result.
Give comparison images similar framing. A sharply cropped “correct” setting beside a distant, blurry “incorrect” one forces readers to hunt for the difference. Matching the scale, crop, and labels keeps attention on what changed. If the difference is a single checkbox, highlighting it may be better than showing two whole windows.
Make annotations carry information, not decoration
Every arrow, box, or callout should direct attention for a reason. Numbered labels can clarify a sequence; one outline may be enough for a single setting. Do not cover the value readers need to inspect, and check that labels remain legible at the article’s normal mobile width.
Never rely on color alone. If green marks expected output and red marks an error, add labels such as “Expected” and “Error.” The distinction will then remain clear to readers who cannot distinguish the colors or who print the image in grayscale. Match the article’s terminology, too: if the prose says “Project SDK,” do not call the same field “Java path” in the image.
An annotation should answer a question faster than a search through the paragraph. If the image needs long explanatory sentences inside it, simplify the graphic and put the explanation in accessible HTML text.
Protect privacy and keep security examples safe
Screenshots can reveal more than you intended. Before publishing, check terminal history, browser tabs, account names, email addresses, API keys, private repository names, IP addresses, session tokens, and file paths. Blurring a secret is not always enough: an earlier exported file may still contain it, and visible fragments can disclose sensitive information. Use fabricated values in a fresh capture or replace sensitive content before export, then inspect the final file.
In cybersecurity material, show diagnostics only in an isolated lab or on a system you administer, and state the authorized scope nearby. Do not include third-party host details just to make an image look realistic. A local sample domain or clearly fictional account is safer for a configuration walkthrough than a real organization’s dashboard.
Check file metadata before uploading, especially for photos taken at home or work. It may contain location data or other information you did not mean to share. If you need to keep an unredacted original, store it in an appropriately protected working location. The published file should contain no hidden private details.
Write alt text for the image’s actual role
Alt text gives readers an alternative when they cannot see an image or it does not load. Describe the information the image adds, not its appearance. For a screenshot, “Project SDK field set to the installed JDK” works if that is what it shows. For a diagram, describe the relationship: “Local browser requests pass through the development server before reaching the application.” A caption can provide different context rather than repeat the alt text word for word.
If substantial text in an image is essential to the lesson, include it in the article. Alt text is not the place for a full terminal session or dense configuration file. Nor should an image be the only source of a required step: readers should be able to follow the written instructions without it.
Captions can mention the software version shown or explain why a highlighted result matters. Under a permissions diagram, for example, a caption might say that the image shows a local practice file, not a setting recommended for every system. That keeps a teaching example from looking like a universal rule.
Check size, placement, and maintenance cost
Place an image close to the passage it supports. Introduce the point, show the image, then explain anything that is not obvious. If readers must scroll through several paragraphs to find a screenshot, comparing it with the instruction becomes harder. Avoid piling up large images without explaining what changes between them.
Check the page at mobile width. Fine terminal text and tiny labels may become unreadable; side-by-side screenshots often fare badly on a phone. One tightly cropped screenshot or two images in sequence may work better than a wide composite. Export at a resolution that stays clear at its displayed size, compress without smearing important text, and skip extra pixels that add nothing useful.
Plan to maintain each image. Note what could make it inaccurate: an IDE redesign, changed command output, a new Linux distribution release, or an updated default. Where an interface is likely to change, explain durable labels and concepts in the prose. When you revise a tutorial, check each image against the current steps; a button that still exists may no longer do the same thing.
A final pass using one example
Suppose a beginner’s Linux guide explains how to inspect permissions on a practice file. Keep the command and sample output as selectable text. Add a compact diagram only if it makes the permission characters easier to map to owner, group, and other users. Label those groups, identify the file as a local practice example, and check every displayed character against the explanation. Then view the diagram on a phone. If the mapping is harder to read there than it is in the text, leave the diagram out.
