How to Name and Organize Screenshots for Documentation Projects

Every documentation team reaches the same breaking point. The screenshot folder has grown to hundreds of files with names like Screenshot 2025-11-15 at 14.32.07.png, IMG_4521.png, and final_FINAL_v2.png. Nobody can find anything. Updating a screenshot means opening dozens of files to find the right one. Duplicate captures waste storage and create confusion about which version is current.

The fix is not a better search tool — it is a naming and organization system established before the chaos begins. And if the chaos has already begun, the fix is migrating to a system now, before the problem compounds further.

Key Insight: Documentation teams that adopt a consistent naming convention report spending 60% less time managing screenshot assets. The convention takes minutes to establish but saves hours every month as the documentation library grows.

This guide covers the naming conventions, folder structures, and management practices that keep screenshot libraries organized at any scale.

Why Default Screenshot Names Fail

Operating systems and screenshot tools assign default names that are useless for documentation purposes.

macOS generates names like Screenshot 2025-11-15 at 14.32.07.png. The timestamp tells you when the screenshot was taken but nothing about what it contains.

Windows uses Screenshot (1).png, Screenshot (2).png, incrementing forever. The number tells you even less than a timestamp.

Browser extensions vary wildly, producing names based on the page URL, the date, or a random hash.

None of these defaults answer the question that matters: "What is in this image?" When you need to update a screenshot six months later, you need to identify it by content, not by capture time. Without meaningful names, you are forced to open and preview every file — a task that becomes unbearable once you pass fifty screenshots.

Common Mistake: Relying on folder location instead of file names for organization. Folders provide one dimension of organization, but when you move, copy, or reference files outside their original folder, the name is all you have. A file named onboarding-step-3-enable-sso.png is self-documenting regardless of where it lives.

Building a Naming Convention

A good naming convention balances descriptiveness with brevity. Names should be long enough to identify the content but short enough to read at a glance in a file browser.

The Recommended Format

[project]-[section]-[step]-[description].[ext]

Components:

Project — The documentation project or product name (e.g., dashboard, onboarding, admin)
Section — The section or feature being documented (e.g., settings, users, billing)
Step — A numeric indicator of sequence within the section (e.g., 01, 02, 03)
Description — A brief description of the screenshot content (e.g., enable-sso, confirm-dialog, success-message)
Extension — The file format (.png is standard for documentation screenshots)

Examples:

onboarding-setup-01-create-account.png
onboarding-setup-02-verify-email.png
onboarding-setup-03-enable-sso.png
admin-users-01-invite-member.png
admin-users-02-set-permissions.png

Naming Rules

Use lowercase only. Mixed case creates inconsistencies and causes problems on case-sensitive file systems.

Use hyphens, not spaces or underscores. Hyphens are URL-safe, readable, and universally compatible across operating systems and build tools.

Use zero-padded numbers. Write 01 instead of 1 so files sort correctly when you have more than nine steps.

Keep descriptions to three words maximum. Longer descriptions make file names unwieldy. If three words cannot describe the screenshot, the screenshot may be trying to show too much.

Pro Tip: When working with ScreenGuide, screenshots captured during guided workflows are automatically sequenced. You can batch-rename the exported files to match your naming convention using the step numbers that ScreenGuide assigns, making the naming process systematic rather than manual.

Designing a Folder Structure

Naming conventions handle file-level identification. Folder structures handle project-level organization.

Structure by Project and Section

screenshots/
  onboarding/
    setup/
    configuration/
    first-use/
  admin/
    users/
    billing/
    settings/
  integrations/
    slack/
    github/
    jira/

This structure mirrors the documentation structure itself. When you are writing the onboarding setup guide, you know exactly where to find and store the corresponding screenshots.

Structure by Date and Version

For teams that produce versioned documentation (e.g., documenting each product release), add a version or date layer:

screenshots/
  v3.2/
    onboarding/
    admin/
  v3.1/
    onboarding/
    admin/

This makes it easy to identify which screenshots belong to which product version and to archive older versions when they are no longer needed.

Flat vs. Nested Structures

Flat structures work for small projects with fewer than 50 screenshots. Everything lives in one folder, and the naming convention carries the organizational burden.

Nested structures work for larger projects. When you exceed 50 screenshots, folders prevent the file browser from becoming an unscrollable wall of files.

Key Insight: The folder structure should mirror your documentation's information architecture. If your docs are organized by feature, organize your screenshots by feature. If your docs are organized by user role, organize your screenshots by user role. Alignment between doc structure and screenshot structure eliminates the mental mapping step when you need to find or update an image.

Managing Screenshots at Scale

Naming and folder structures are the foundation. At scale, additional practices keep the system functioning.

Version Control for Screenshots

Treat screenshots like code. Store them in version control (Git, for example) so you have a history of changes, can revert to previous versions, and can track who updated which screenshots and when.

Practical considerations for screenshots in Git:

Use Git LFS (Large File Storage) for repositories with many screenshots. Standard Git tracks every version of every file, and binary image files bloat the repository quickly.
Commit screenshots alongside the documentation they support. This ensures that documentation text and its screenshots stay in sync.
Write meaningful commit messages — "Update billing screenshots for v3.2 redesign" is infinitely more useful than "Update images."

Asset Inventories

Maintain a spreadsheet or database that maps each screenshot file to the documentation page where it is used. This inventory serves two purposes:

Update tracking — When the UI changes, the inventory tells you which screenshots need updating and which documentation pages are affected.
Orphan detection — Screenshots that are not referenced by any documentation page are orphans. They should be archived or deleted to keep the library clean.

Pro Tip: Automate orphan detection by scripting a comparison between your screenshot folder contents and the image references in your documentation files. Any file present in the folder but not referenced in the docs is a candidate for removal.

Bulk Renaming

When migrating from an unnamed screenshot library to a named one, bulk renaming tools save enormous time.

macOS — Finder supports basic batch renaming (select files, right-click, Rename)
Windows — PowerToys includes an advanced batch renaming tool
Cross-platform — Tools like rename, mmv, or Python scripts handle complex renaming patterns

The process:

Open each unnamed screenshot and identify its content.
Determine the correct name according to your naming convention.
Apply the rename.
Update all references to the file in your documentation.

Step 4 is the critical one. Renaming a file without updating references breaks image links in your documentation. Search your documentation source files for the old filename and replace all occurrences with the new one.

Screenshot Formats and Their Trade-offs

The file format you choose affects quality, file size, and compatibility.

PNG is the standard for documentation screenshots. It uses lossless compression, preserves text sharpness, supports transparency, and is universally supported. Use PNG as your default.

JPEG uses lossy compression, which produces smaller files but introduces artifacts around text and sharp edges. Avoid JPEG for screenshots containing text or UI elements.

WebP offers better compression than PNG with comparable quality. It is well-supported in modern browsers and is a good choice for web-published documentation where page load speed matters.

SVG is not suitable for screenshots but is excellent for diagrams and annotated overlays. Some documentation teams capture screenshots as PNG and add annotation layers as SVG.

Common Mistake: Saving screenshots as JPEG to reduce file size. The compression artifacts around text make documentation look unprofessional. If file size is a concern, use PNG with compression optimization tools like pngquant or optipng, or convert to WebP for web delivery.

Integrating With Documentation Platforms

Your naming and organization system should integrate smoothly with your documentation platform.

Static site generators (Docusaurus, Next.js, Hugo) reference images by file path. A well-organized folder structure maps directly to clean image paths in your source files.

Wiki platforms (Confluence, Notion) upload images into their own storage. Maintaining a local mirror with your naming convention ensures you can re-upload or update screenshots without losing track of which image belongs where.

CMS platforms (WordPress, Contentful) often rename files on upload. Name files before uploading and maintain a mapping between your local names and the CMS-assigned names.

ScreenGuide exports guides with screenshots that can be named and organized according to your conventions before importing into any platform. This keeps the workflow consistent regardless of the destination.

Establishing Team Conventions

A naming convention only works if everyone follows it. Establish team norms to ensure consistency.

Document the convention. Write a one-page reference that covers the naming format, folder structure, approved file formats, and examples. Store this reference where your team will actually find it — pinned in the documentation channel, linked from the project README, or included in the documentation template.

Automate enforcement. Add a linting step to your documentation build process that checks screenshot file names against the convention. Flag non-conforming names as build warnings or errors.

Review during pull requests. When reviewing documentation changes, check that new screenshots follow the naming convention and are placed in the correct folder. This is easier to enforce than it sounds — reviewers naturally look at file paths in diffs.

TL;DR

Default screenshot names like Screenshot 2025-11-15 at 14.32.07.png are useless for documentation management — adopt a descriptive naming convention immediately.

Use the format [project]-[section]-[step]-[description].png with lowercase, hyphens, and zero-padded numbers.

Design folder structures that mirror your documentation's information architecture for intuitive navigation.

Use Git with LFS for version control and maintain an asset inventory to track where each screenshot is used.

Default to PNG format for screenshots — avoid JPEG compression artifacts on text and UI elements.

Document the convention, automate enforcement, and review during pull requests to ensure team-wide adoption.

Ready to create better documentation?

ScreenGuide turns screenshots into step-by-step guides with AI. Try it free — no account required.

Try ScreenGuide Free