Writing copy
In the portal: Settings, then Atoms. The words live on the atom.
The one rule
Every screen does something, or it gets cut.
Read each screen and ask one question: is this screen doing something, or describing something? A screen that describes either gains a real control or it goes. There is no third answer, and applying this honestly is the single biggest improvement you can make to a programme you have already written.
Cutting on this rule makes a programme better rather than thinner. Fewer taps to the thing that matters, and nothing on screen the product cannot back up.
Two screens that always fail it
Announcing something the programme cannot do. A screen offers to put the participant's reason for joining on their reminder, in a programme where nothing has ever asked for a reason and no reminder can carry one. The fix is not better wording. Capture the reason once, at the point it is earned, then show their own words back later. Never offer what you have nowhere to store.
Promising a kindness before the failure. A screen says "miss one and nothing breaks" to somebody who has not missed anything, about a habit they have not started. It is reassurance written by the author for the author. Cut it, and let the recovery content say it at the moment it means something. A coach does not tell you in advance that they will not mind. They simply do not mind, later, once, out loud.
How long
A card is one idea. If a card has two ideas, it is two cards, or it is one card and a question.
A prompt is a question, not a paragraph. The prompt sits above the control on one
block of rich text. Anything longer belongs in a content atom above it.
The home item has three lines for its title and two for its description, and it wraps rather than trailing off. A title that needs four lines is not a title.
A surface heading and its description get one line each. Treat 60 characters as the real limit on a surface description, whatever the field will accept.
Nothing is truncated. Every word you write is shown in full, so length is your decision rather than the platform's. Long copy reflows and pushes the control further down the screen, so keep it short enough that the control stays in view.
How it sounds
Warm, plain and not clinical. Write "how you have been sleeping", not "sleep disturbance". Write "how you are doing", not "symptom burden".
Say why before you ask. A question with no reason in front of it reads as a form. One sentence of why turns the same question into a conversation.
Offer the gentler option at every choice point. Where a screen offers "I am ready", it also offers "tell me more first". A programme with only one door is a programme people leave.
Start small and build. The first thing you ask anybody to do should be smaller than you think is worth asking.
Never write copy that reads a gap as a failure. Nothing on the Progress tab knows why somebody did not answer. "No data" means never answered, not "you lapsed". Copy that assumes the worse reading will be wrong for a great many people, and they will be the ones who most needed it to be right.
Copy must never contradict the mechanics. If the words say a streak survives a missed day, the mechanics have to survive a missed day. A participant who catches the product being untrue about something small stops believing it about everything.
Quoting them back to themselves
A {{ }} token in an atom's prompt or a content atom's body is replaced with a
real value: something the participant told you earlier in the same sequence, an
answer from a previous questionnaire, or a value set when they joined.
This is the cheapest way to make a programme feel like it is paying attention rather than handing somebody a worksheet. It is worth reaching for wherever a person has told you something in their own language.
A worked example. In week one a text atom, coded WHY_NOW, asks: In your own
words, what do you want to be able to do again? She writes get back on the bike with my daughter.
In week six a content atom says:
You told us in week one why you started:
{{ latestAtomResponse.<the WHY_NOW atom's id> }}
Still true, or has it changed?
She reads her own sentence back, six weeks later, in her words. Nothing about that card is written for her specifically. It is one card, delivered to everybody on that journey, and each person sees their own answer in it.
That is the whole idea, and it is also why the rules below matter: the quote sits on its own line after a colon, so the card still reads properly for somebody who skipped the week one question.
Four rules follow. The first two are where things usually go wrong.
A missing value renders as nothing. So write the sentence so that it survives
an empty token. "You said you wanted to change {{ }}" reads badly with nothing
in it. The same quote on its own line after a colon reads fine.
A token has two parts: where the answer comes from, then which answer. Quoting an
answer from earlier in the same sequence names the atom by its readable code,
{{ values.WHY_NOW }}. Quoting one given on an earlier day names the atom by its id.
A token carrying only a code, {{ WHY_NOW }}, finds nothing. If a token is coming out
empty, check that first. Autofill has the three ranges and worked examples
for each.
The token adds no default, no capitalisation and no date formatting. Write the sentence so it reads properly whatever comes back, and never start a sentence with a token, because nothing will capitalise it.
There is one exception. A single select, a multi select or a yes-or-no question hands back the label the participant read, not the value stored underneath it. Autofill has the detail, including how to ask for the stored value instead.
Write pushes, emails, text messages and chat messages verbatim. All four leave the app and are sent exactly as typed, so a token in one of them reaches the participant as literal braces. Tokens are for the screens inside the app, which is also why nothing a participant has told you travels out through a message.
When one card has to say two things
A sequence's name is one string for everybody. So keep the title neutral and move the words that change into an atom, which can carry its own condition.
Two rules that decide whether that works.
Write the variants as separate positive conditions, one per variant, because a condition decides when an atom shows.
Leave one unconditional atom on the page. Conditions are read against what the participant has already answered, so on a first run a page whose atoms are all conditional may have nothing to show. One unconditional atom means the card always says something.
Before you ship it
Walk the programme on a phone rather than reading it on a screen. Every failure worth catching was caught by walking it, and none of them by reading it.
[ ] Every screen has a control, or it has been cut
[ ] No screen announces a capability the programme does not have
[ ] No screen offers reassurance about a failure that has not happened
[ ] Every question has one sentence of why in front of it
[ ] Every choice point offers a gentler alternative
[ ] Every title fits three lines and every item description fits two
[ ] Every token names an atom that has a code
[ ] Every sentence with a token still reads with the token empty
[ ] No token in a push notification, an email or a text message
[ ] Every page carrying a conditional atom also carries an unconditional one
[ ] No copy that treats an unanswered day as a lapse
[ ] Nothing the words promise that the mechanics do not do