Naming documents and files so that they sort, search and survive

What it is

A naming convention answers, for one folder or one class of document, which pieces of information go into the name, in what order, with which separators, and from which characters. POSIX (cited) defines a portable filename character set of letters, digits, period, underscore and hyphen, and notes that a leading hyphen causes trouble when names are passed as command-line arguments. RFC 3339 (cited) observes that when date and time components are ordered from least precise to most precise, string order equals chronological order, provided the same time zone and precision are used. The cited Harvard data-management guidance recommends YYYYMMDD dates, YYYYMMDDThhmm timestamps and leading zeros in sequence numbers for the same reason.

Why it matters

Names are read in file listings, search results, URLs, log lines and command lines, usually without the content. A name that sorts wrong, needs quoting, or differs only in case from another costs a little every time it is touched. Names of published documents become links; renaming them breaks the links.

How to apply

• Decide the components and their order once: {date}-{type}-{subject} for time-ordered items (2026-09-15-incident-report-upload-failures.md), {subject}-{qualifier} for identity-ordered ones (invoice-template-v3.docx).
• Use the portable character set, lowercase throughout, hyphens between words; if fields must be separable, use one separator between fields and another within them, and say which.
• Write dates as YYYY-MM-DD (or YYYYMMDD where hyphens are used elsewhere) and pad sequence numbers to a fixed width (007).
• Mark versions explicitly (v2, a date, or a commit hash) and never with "final", "new" or "latest".
• Never rely on case or on spaces; case-insensitive file systems treat Report.md and report.md as the same file, and spaces need quoting everywhere.
• Keep the name short and put the full title inside the document; the name identifies, the content describes.
• Write the convention in a README in the folder, and rename with the version control tool so history follows the file.

Pitfalls

DD-MM-YYYY dates that sort by day. Non-ASCII characters, which file systems normalise differently. Names that encode information also stored elsewhere and then disagree with it. Renaming published files without leaving a redirect. Very long names that exceed path limits in some tools.