Persona template in Markdown: one reader, one file

Describe an invented reader with this persona template for a plain .md file. You can put the person's situation, questions about a page, unfamiliar words, and needed background together. The focus is one kind of reader approaching one page, which may be drafted by a person or come from AI agents.

Begin with a blank copy and substitute a reader description for the placeholders. You can use any plain text editor for the description. The filled-in example concerns returning borrowed books, with Jane Doe as the invented person reading about that task.

Purpose of a persona file

A persona here means a description of an invented kind of reader of a particular page. You describe what that person knows about the subject and what they want to understand by reading. In this post's form, you also describe what confuses the person and the words they would use.

The Markdown style guide template concerns voice, word choices, and writing conventions for a team's pages. In this persona file, you describe who reads those pages; you keep the writing choices in the separate style guide.

With the glossary template for Markdown, you can pair project terms with brief meanings. Here, you describe the invented reader's familiarity with the subject, including a term they don't understand; you can keep a fuller set of meanings in a glossary.

The boundary of this portrait is the person's relationship to the page. For example, you can describe familiarity with borrowing books without adding a personal history. You write about what the person knows and wants to learn from the page, with the page's subject as the limit of the description.

Blank persona template

Use the following blank form for this post's Markdown persona template. Write a short reader description in place of the paragraph placeholder. Replace the dash-line placeholders with details about that same invented person and the page they are reading.

# Reader in a few words

## Who they are

Describe what the person does in relation to the page. Describe what they already know about its subject. Add a third sentence about their familiarity if needed.

## What they want from the page

- Name a question the person wants answered.
- Name another question about the same subject.

## What trips them up

- Describe an unfamiliar term or a point of confusion.

## Their words

- Write a short phrase the person would use about the subject.

## Background for the reader

- Name the background the person needs before the details.

Read the parts as descriptions of a reader in relation to a page:

• Title phrase. Name the reader's situation in a few words after #. You can leave the questions and the background for the parts beneath it.
• Who they are. Write two or three sentences about the person's connection to the page and their familiarity with the subject. In the example, Jane Doe knows the room where books go back but hasn't returned one before.
• What they want from the page. Name the questions this person brings to the subject. The blank form has room for two questions, and the example concerns where to put a book and whom to tell afterward.
• What trips them up. Describe a point of confusion in a short dash line. Jane Doe's confusion concerns a phrase used for returning a book.
• Their words. Write a brief phrase in the invented person's own plain wording. You can phrase it as a question, as Jane Doe does in the example.
• Background for the reader. Name the background the person needs before the details. In the example, that background concerns where Jane Doe puts the returned book.

For a separate look at Markdown bullet points, you can read comparisons of dash lists with different gaps between the lines. Here, an empty line sits between each heading and its dash lines.

Filled-in Doe sample

Both names here are invented: Doe Holdings and the reader, Jane Doe. As the made-up reader, she wants to understand a page about returning a borrowed book at Doe Holdings. Her description concerns that task and the wording around it.

# First return of a borrowed book

## Who they are

Jane Doe borrows books at Doe Holdings. She knows the room where books go back but has not returned one before.

## What they want from the page

- Jane Doe wants to know where to put a returned book.
- She wants to know whom to tell after putting it there.

## What trips them up

- Jane Doe does not understand the phrase return spot.

## Their words

- Where do I put the book when I am done with it?

## Background for the reader

- Jane Doe needs to know that she puts returned books on the lower shelf.

Jane Doe's paragraph has two sentences about her connection to the task. In the part about what she wants from the page, she has two questions about the return. In the part about what trips her up, the phrase return spot is unfamiliar to her.

The I in the words line stands for Jane Doe. She asks about the book in words that don't include the unfamiliar phrase. In the final part, she needs to know where returned books go before the details about telling someone.

Length of each part

A brief description and short dash lines are the length aims of this form. Consider the paragraph and dash lines in the example:

• A paragraph about the task. Keep the description close to what the person does with the page's subject. Jane Doe's paragraph concerns borrowing and returning books, without a longer account of her life.
• Questions in brief lines. Name the specific questions in the part about what the person wants from the page. Jane Doe asks about a place and a person to tell.
• A phrase for the difficulty. Keep the confusion line about a named difficulty. Jane Doe's unfamiliar phrase is return spot, with no extended discussion of other book terms.
• Plain wording for the person. Keep the phrase in the words part close to the person's question about the subject. Jane Doe asks where to put the book in a short question of her own.
• Background within the same task. Keep the final line tied to the questions above it. Jane Doe needs to know where returned books go.

File name for a persona

Keep the reader description together in one .md file in this setup. For Jane Doe's situation, you could name it book-return-persona.md. The name concerns the book return and the type of description; you keep the person's questions and unfamiliar phrase inside the file.

You can place this portrait next to a separate style guide.

Where Sashmark fits

For people whose .md text comes from AI agents, a desktop Markdown editor and reader called Sashmark is planned. This desktop app is being built now, and people cannot get any part of it. Project folders where persona files sit among other .md work are the kind Sashmark is planned for.

See the planned features, the help pages and the roadmap for where each part stands.

Visit sashmark.com.