Error message template in Markdown: calm, specific wording

An error message has a small writing job: tell a reader what failed, explain the situation briefly and name a choice they can make next. This Markdown error message template keeps those words together while they are being drafted, before they go into an invented app's interface.

Treat each file as a draft of a single message. Leave investigation of the failure and any wider interruption outside this wording draft. Start with the situation already established, then write only what the person facing that situation needs to read.

A draft title and a message heading

The draft title belongs to the writing file. Begin with [Draft title] as a temporary name for the message draft. That title can be longer than the heading a reader would see in the app.

The message heading names the action that failed. "Drawing could not open" gives the sentence beneath it a definite subject. "Something happened" leaves that subject unstated. Aim for a short heading that remains meaningful when read on its own.

A file ending in .md can hold this draft; the .md extension explains the extension. The Markdown headings here divide the writing into parts, rather than specifying how the interface will look.

The error message template

For this example, fictional writer Jane Doe is preparing wording for an invented app called Doe. In this made-up situation, the app cannot open a drawing because that drawing has no saved shapes. The next choice in this invented app opens a different drawing. Neither the person nor the app represents a real one.

# [Draft title]

Fictional Jane Doe drafts this message for the invented Doe app.

## Drawing could not open

This drawing has no saved shapes to open.

Next action label: Choose another drawing

Tone note: State the situation plainly, without blaming the reader.

Replace the heading, explanatory sentence and action label to suit the single message you are drafting. Retain the title placeholder until you name the draft. Rewrite the tone note when the wording needs a different emphasis, while keeping it separate from the message itself.

For the enclosing fence syntax, see Markdown code blocks. The fence displays this example as text you can copy; the app message excludes that fence.

One sentence beneath the heading

The heading says that opening the drawing failed. The sentence gives the particular reason established in Jane Doe's invented situation: there are no saved shapes in that drawing. It adds detail without repeating the heading in longer words.

Write the explanation using the facts you have for that message. If a reason is unknown, leave that reason unstated instead of guessing what the reader did. Describe the current situation specifically, leaving responsibility unassigned.

Keep this sentence close to the failed action. Extra history about how the app was built would pull the draft away from the words the reader needs at that moment. Before adding another sentence, look for two ideas competing within the first and simplify the phrasing.

A next action the reader can choose

"Choose another drawing" names the next choice in this fictional Doe app. It does not promise that the current drawing will open if the reader repeats the same action. The label and the invented choice match.

Use a verb and the thing acted on when that wording fits the choice. A label such as "Continue" needs surrounding text to explain where it leads. For this example, naming another drawing states the destination directly.

Keep the label in the draft even when it is only a few words. The heading, explanation and action label need to make sense together: a sentence about one drawing followed by a choice concerning that drawing or another one.

Calm wording without blame

The tone note concerns how the message is written. Jane Doe's note asks for a plain description without blame. It stays in the drafting file; the reader-facing message consists of the short heading, explanatory sentence and action label.

Avoid accusing the reader of causing the failure. "You forgot to save shapes" would add an assumption about their conduct to this invented situation. The example instead describes what the drawing contains. That choice keeps the sentence focused on the reason already given.

Calm wording also leaves out jokes, dramatic punctuation and claims that the problem is trivial. You can name a failed action directly without telling the person how they should feel about it. Read the three message parts together and revise any phrase that adds judgment rather than useful meaning.

Naming the message draft file

A filename such as drawing-could-not-open.md identifies the message being drafted. Keep one message in the file so a change to its explanation remains beside its heading and action label. For descriptive names and word separators, consult naming Markdown drafts.

The file title can remain [Draft title] during early wording changes. Once the message has a clear subject, give that title a descriptive name too. The filename and title identify the draft; neither needs to become text in the app.

Where Sashmark fits

Sashmark's intended audience receives Markdown from agents. Desktop reading and editing are planned; Sashmark remains in development.