Help text on the fields that need one: 167 of 240 form fields explain nothing beyond their label #205

New issue

Closed

opened 2026-09-15 11:30:45 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-09-15 11:30:45 +00:00

Owner

Observation

Most fields in Postulo's forms carry no help text. A count over every form class in
accounts, jobs, applications, resume, documents, core and plugins:
240 fields, 73 with a help text, 167 without. Where a field has one it is good — the
telephone box explains the international form, the Gravatar box says what is fetched and
when, the capture form says what a default is since #179 — and where it does not, the
label is doing all the work. A label can name a field; it cannot say what goes in it,
in what form, or what Postulo does with it.

partials/field.html already draws help_text under every field through
field_feedback.html, so nothing structural is missing. What is missing is the sentences.

The fields worth one

Not every field. Name, First name, Title need nothing. These are the ones where the
meaning, the expected form or the consequence is not obvious from the label, grouped by
form (base_fields without help_text, as of main today):

A posting (JobPostingForm, PostingIntakeForm, ApplicationIntakeForm — the same
thirteen fields, three times)

salary_min / salary_max — gross or net, per what; whether one bound alone is fine.
salary_currency / salary_period — that they mean nothing without an amount (#176).
remote_type — what each of the three means; hybrid in particular.
employment_type — that it is Postulo's vocabulary and a board's word may not map.
source — the board or route it was found on, as words: what it is for (the report's
tally by source, #56).
url — the posting's own address, what Postulo does and never does with it (never
fetched again).
closes_at / posted_at — read off the page where there was one; blank means unknown.
description — pasted text; what is kept and that nothing is fetched.

An application (ApplicationForm, ApplicationDetailsForm)

channel — applied through: which route, and that it feeds the report.
priority — what it changes (the board's order, the dashboard's chasing).
deadline — whose deadline: the employer's, not a reminder.
tags — free words, one per tag, made as typed.
contact — the person at the company this went through.

Interviews and reminders (InterviewForm, ReminderForm, EventForm)

starts_at / ends_at — in your time zone (Settings → Language and time), and that
the calendar file carries it in UTC.
contacts — the people you are meeting; picked from the company's contacts.
notes — preparation notes, yours; never sent anywhere.
due_at — when to be reminded, in your time zone; what a notifier does with it.
summary (event) / body — what the timeline shows, and what it keeps.

A company and its people (CompanyForm, ContactForm)

website — used for Find logo and nothing else, and only when pressed.
location — free text, as it should read on the page; not geocoded.
industries — several, comma-separated, made as typed; the NACE codes come from the
Industries page.
notes — yours.
role — the person's job title as they give it.

The career record (ExperienceForm, EducationForm, ProjectForm,
CertificationForm, LanguageSkillForm, LinkForm, SkillForm)

start_date / end_date — a month is enough; blank end means ongoing, and what a CV
prints for it.
highlights — one per line, rendered as bullets (the wiki says so; the field does not).
summary — one paragraph, and where it lands on a CV.
credential_url / expires_on — what a CV prints of them.
proficiency — the scale used, with a word for each level.
kind (link) — that it describes the sort of thing, never the host (#189's rule).
group (skill) — how skills group on a CV.

Documents (CVForm, CoverLetterForm, UploadedDocumentForm, SendDocumentsForm)

kind — what tells a portfolio from a CV, or a cover letter from a motivation letter.
headline — where it prints and that it overrides the profile's.
theme — that it can be changed later without touching the content.
subject — printed at the top, and the placeholders it may hold.
file — what is accepted, the size, and that the extension is kept (#193).
links (send) — what sending a link records.

Settings and server (LocaleForm, DefaultsForm, EmailForm, TestEmailForm)

language / time_zone — what each changes and what it does not (the career record's
language is its own field, #131).
default_language / default_time_zone — that they are what a new account starts with.
email_host, email_port, email_username, email_from, email_timeout, the
three OAuth fields — the form that most needs sentences and has the fewest: what each
is, what a typical value looks like, which are required for which security mode.

Accounts (SignupForm, AddPasskeyForm, PersonIdentifierForm)

username — what it is used for and where it shows.
name (passkey) — a name for the device, for the list.
scheme / value — the What goes where fold exists on the profile page (#46); the
form itself says nothing.

What a fix has to settle

Voice. The help texts Postulo has are short, in the second person, and say the
consequence rather than restate the label (Kept in the international form, so it can
be dialled from anywhere). The new ones are written in that register, and none says
"Enter the …".
Once, not three times. The posting's thirteen fields are declared in three forms;
the sentences live on the fields they share (PostingIntakeForm) and the others inherit.
Every sentence is a string: English, French and European Portuguese while working,
the sweep at the release, as the rule says (#182). That is the real cost — roughly
eighty sentences.
The wiki says some of these already (highlights as bullets, the month granularity
of dates); the field and the page should agree, and the field is where it is read.
A test that lists the fields still without help, so the list above is a snapshot and
not a promise: the shape test_page_coverage.py uses, with an excused set for the
fields that need nothing.

## Observation Most fields in Postulo's forms carry no help text. A count over every form class in `accounts`, `jobs`, `applications`, `resume`, `documents`, `core` and `plugins`: **240 fields, 73 with a help text, 167 without.** Where a field has one it is good — the telephone box explains the international form, the Gravatar box says what is fetched and when, the capture form says what a *default* is since #179 — and where it does not, the label is doing all the work. A label can name a field; it cannot say what goes in it, in what form, or what Postulo does with it. `partials/field.html` already draws `help_text` under every field through `field_feedback.html`, so nothing structural is missing. What is missing is the sentences. ## The fields worth one Not every field. *Name*, *First name*, *Title* need nothing. These are the ones where the meaning, the expected form or the consequence is not obvious from the label, grouped by form (`base_fields` without `help_text`, as of `main` today): **A posting** (`JobPostingForm`, `PostingIntakeForm`, `ApplicationIntakeForm` — the same thirteen fields, three times) - `salary_min` / `salary_max` — gross or net, per what; whether one bound alone is fine. - `salary_currency` / `salary_period` — that they mean nothing without an amount (#176). - `remote_type` — what each of the three means; *hybrid* in particular. - `employment_type` — that it is Postulo's vocabulary and a board's word may not map. - `source` — the board or route it was found on, as words: what it is for (the report's tally by source, #56). - `url` — the posting's own address, what Postulo does and never does with it (never fetched again). - `closes_at` / `posted_at` — read off the page where there was one; blank means unknown. - `description` — pasted text; what is kept and that nothing is fetched. **An application** (`ApplicationForm`, `ApplicationDetailsForm`) - `channel` — *applied through*: which route, and that it feeds the report. - `priority` — what it changes (the board's order, the dashboard's chasing). - `deadline` — whose deadline: the employer's, not a reminder. - `tags` — free words, one per tag, made as typed. - `contact` — the person at the company this went through. **Interviews and reminders** (`InterviewForm`, `ReminderForm`, `EventForm`) - `starts_at` / `ends_at` — in your time zone (*Settings → Language and time*), and that the calendar file carries it in UTC. - `contacts` — the people you are meeting; picked from the company's contacts. - `notes` — preparation notes, yours; never sent anywhere. - `due_at` — when to be reminded, in your time zone; what a notifier does with it. - `summary` (event) / `body` — what the timeline shows, and what it keeps. **A company and its people** (`CompanyForm`, `ContactForm`) - `website` — used for *Find logo* and nothing else, and only when pressed. - `location` — free text, as it should read on the page; not geocoded. - `industries` — several, comma-separated, made as typed; the NACE codes come from the Industries page. - `notes` — yours. - `role` — the person's job title as they give it. **The career record** (`ExperienceForm`, `EducationForm`, `ProjectForm`, `CertificationForm`, `LanguageSkillForm`, `LinkForm`, `SkillForm`) - `start_date` / `end_date` — a month is enough; blank end means ongoing, and what a CV prints for it. - `highlights` — one per line, rendered as bullets (the wiki says so; the field does not). - `summary` — one paragraph, and where it lands on a CV. - `credential_url` / `expires_on` — what a CV prints of them. - `proficiency` — the scale used, with a word for each level. - `kind` (link) — that it describes the sort of thing, never the host (#189's rule). - `group` (skill) — how skills group on a CV. **Documents** (`CVForm`, `CoverLetterForm`, `UploadedDocumentForm`, `SendDocumentsForm`) - `kind` — what tells a portfolio from a CV, or a cover letter from a motivation letter. - `headline` — where it prints and that it overrides the profile's. - `theme` — that it can be changed later without touching the content. - `subject` — printed at the top, and the placeholders it may hold. - `file` — what is accepted, the size, and that the extension is kept (#193). - `links` (send) — what *sending a link* records. **Settings and server** (`LocaleForm`, `DefaultsForm`, `EmailForm`, `TestEmailForm`) - `language` / `time_zone` — what each changes and what it does not (the career record's language is its own field, #131). - `default_language` / `default_time_zone` — that they are what a new account starts with. - `email_host`, `email_port`, `email_username`, `email_from`, `email_timeout`, the three OAuth fields — the form that most needs sentences and has the fewest: what each is, what a typical value looks like, which are required for which security mode. **Accounts** (`SignupForm`, `AddPasskeyForm`, `PersonIdentifierForm`) - `username` — what it is used for and where it shows. - `name` (passkey) — a name for the device, for the list. - `scheme` / `value` — the *What goes where* fold exists on the profile page (#46); the form itself says nothing. ## What a fix has to settle - **Voice.** The help texts Postulo has are short, in the second person, and say the consequence rather than restate the label (*Kept in the international form, so it can be dialled from anywhere*). The new ones are written in that register, and none says "Enter the …". - **Once, not three times.** The posting's thirteen fields are declared in three forms; the sentences live on the fields they share (`PostingIntakeForm`) and the others inherit. - **Every sentence is a string**: English, French and European Portuguese while working, the sweep at the release, as the rule says (#182). That is the real cost — roughly eighty sentences. - **The wiki says some of these already** (*highlights* as bullets, the month granularity of dates); the field and the page should agree, and the field is where it is read. - A test that lists the fields still without help, so the list above is a snapshot and not a promise: the shape `test_page_coverage.py` uses, with an excused set for the fields that need nothing.

tiagoagueda added this to the 0.4.0 milestone

2026-09-15 11:30:45 +00:00

tiagoagueda added the

labels

2026-09-15 11:30:45 +00:00

tiagoagueda referenced this issue

2026-09-17 17:26:21 +00:00

Adopt Basecoat for the component layer, while most of the interface is still unwritten #262