Datler Docs

DatlerDocs

Writing in Datler

4 min read

These rules are for anyone writing the words Datler shows or says about itself: labels and help in the app, the glossary, and these docs. Read them before writing UI copy. Each guards against a mistake that is easy to make and easy to miss on review.

Names come from the glossary

  • A concept’s name is its glossary term, read through termWord(id) and termPlural(id) from @datler/core, in a label and in a sentence alike. Look the concept up in packages/core/src/glossary.generated.ts before writing the word (Glossary). “Other ways to count it” for Units is the kind of made-up synonym this rules out.
  • If a term reads badly, rename the term, everywhere at once: its file in docs-vault/content/terms/, the old spelling added to its banned list, then pnpm run docs:gen-glossary (UI Vocabulary and the Info Affordance). Never a friendlier word in one place.
  • No new noun for something that already has one. An entry with a start and an end is an entry, not a “sitting”; describe it by its fields.
  • Retired words stay retired: Folder is Tag; Display and Analysis are Visualization; sitting is entry; Mood is Emotion and Pleasantness; Check-in is Rundown.
  • What a module names (a trackable, a field’s label) is the person’s to rename, but it starts as the term: the Emotion field, the Subject field.

Labels

  • A label is a noun or a short noun phrase: Start name, Entry date, Intensity, Source, Severity. Read each one alone and ask whether it names the thing. A participle is not a label: “Called” is Name, “Dated by” is Entry date, “Counted from” is First day.
  • Never “Its …”, “Each …” or ”… is called”. “Its value”, “Its start is called” and “Its visualizations” are all wrong.
  • An option reads as the thing: Waketime, not “Its waketime”.
  • No heading that restates the page. A Weight page does not need “Weight — its own value” under its title.
  • Every input has a visible label above it, the library’s Field. A placeholder may give an example, never the name: once a value is filled in the placeholder is gone, and a bare box says nothing about what it is for. Where a row is tight (a food’s values, a routine row’s fields), the label may sit beside the box or small above it, but it is always there and always says what the box is; a unit beside a box is not its label. A search box is no exception.
  • A sentence explains fields; it never labels them. “Not until [5] days have a value” hides what the box is once it is read. The label goes above, and the sentence goes beneath as a plain reading of what the fields now say (the Field’s description): “No record counts until 5 days have a value.”
  • A button is a verb (Save, Revert, Log, Exit); a link names where it goes (Issues page).

Sentences in the app

Help text, confirmations, empty states.

  • Plain and short, saying what happens: “12 entries go with it. This cannot be undone.”
  • Say whose, rather than opening with “Its”: “The values this has none of come from Chicken breast”, not “Its values fill the ones this has none of”.
  • The glossary term inside a sentence too: “no stored entries” is termPlural("entry"), and a count is termCount("entry", n), “12 entries”, never a word picked by n === 1; apps/renderer/src/ui-copy.test.ts fails on one.
  • No fixed “a” before a name someone typed: the article follows the name’s sound, and “Deleted a Energy entry” is what a fixed one gives. Phrase around it: “Energy entry deleted”, “Usually in Workout”.
  • No caption explaining the obvious.

The docs

  • A note says how a thing works and why, as information, without the record of who chose it or when: no quotes, no names, no “it was decided”. The reason a design is this way and not the obvious other way belongs in the note, stated plainly (Vault Curation).

The checks

  • pnpm test runs apps/renderer/src/ui-copy.test.ts, which fails on app text that starts with “Its”; on a label, title, aria-label or placeholder with “its” in it, written as a string or as a string inside the expression that chooses it; on an option’s text with “its” in it; and on a fixed “a” or “an” before an interpolated name. It is narrow on purpose: a wide scan of the source for banned words finds far more false hits than real ones.
  • pnpm run docs:check-vocabulary lists the glossary’s banned spellings in this vault.
  • Look at the screen with values filled in, not only at the accessibility tree.

Glossary · UI Vocabulary and the Info Affordance · Vault Curation

Graph View

Backlinks