How to title a document so people can find it. Written after the HubSpot category reached 54 documents and became hard to scan.
The short version
- Start the title with the area it is about, then a colon:
Meetings: set up your booking link. - Never start a title with the product name of the category it already sits in, on the HubSpot page, "HubSpot" is noise.
- Use the controlled area list below, so the same subject always sorts to the same place.
- Write the rest as what the reader gets, in lower case, not a formal document title.
- Put the document in the right folder, that is what decides which group it appears under.
- If it is somebody else's material, start it with
Source:so nobody mistakes it for a HueLife decision.
Why this exists
The HubSpot category has 54 documents, and 24 of them used to begin with the word "HubSpot". Sorted alphabetically, that put almost half the page in a single unreadable block under H, where the only thing distinguishing one entry from the next was the seventh word onwards.
The fix has two halves. Documents are now grouped by what they are for, which is derived from the folder they live in. And titles should lead with the subject, so that scanning a group tells you something.
The pattern
Area: what the reader gets| Instead of | Write | |
|---|---|---|
| ✓ | Set up your HubSpot booking link | Meetings: set up your booking link |
| ✓ | Segment (List) Naming Conventions & Cleanup | Lists: naming conventions |
| ✓ | Custom Contact Field Fill Rates (FULL population), HueLife | Contacts: which custom fields are actually used |
| ✓ | Sequences vs Workflows, when to use which | Workflows: sequences vs workflows |
| ✓ | Making WordPress & Arlo registrants marketable in HubSpot | Contacts: making registrants marketable |
| ✓ | HubSpot CLI commands overview (reference) | CLI: commands overview |
The area list
Keep to these. A new area is fine when something genuinely does not fit, but two words meaning the same thing is how the problem started.
| Area | Covers |
|---|---|
Contacts | Contact records, properties, fields, data quality, marketable status |
Lists | Lists, segments, audiences |
Email | Marketing email, templates, deliverability |
Forms | Forms and what happens after a submission |
Workflows | Automation, sequences, enrolment |
Meetings | Booking links and calendar |
Courses | The Course object, classes, sessions, cohorts |
Campaigns | Campaign records, naming, attribution |
Ads | Ad accounts, pixels, audiences |
Reporting | Dashboards, attribution, analytics |
CLI | The hs command line tool and the developer platform |
AI | Breeze, assistants, agents, MCP |
Audit | The state of our own portal, as found |
Prefixes that are not areas
Source: | Somebody else's material, HubSpot's docs, a vendor blog, a video transcript. Signals "useful, but not our decision." |
Start here: | The one document a newcomer should read first in that area. Use sparingly, two per category at most. |
Where a document goes
The group a document appears under on a category page is derived from its folder, not its title. So putting the file in the right place matters more than what you call it.
| Folder | Appears under |
|---|---|
hubspot-audit/ | Our HubSpot |
planning/, segment-strategy/, class-operations/ | How we work |
hubspot-automation/, smart-email-clients/hubspot-automation/ | Automation & CLI |
onboarding-doc/transcripts/ | Learning |
anything named source-* or *sources* | Reference |
Overrides live at the top of public/_build-category.py for the handful of documents where the
folder is misleading.
Adding a document
- Write the
.htmlfile into the right folder underpublic/. - Add a card for it anywhere in the category page, position does not matter.
- Run
python3 public/_build-category.py public/hubspot.html. It regroups, re-sorts and rebuilds the filter. - Update the count on
index.htmland add an entry tosearch-index.json. - Commit and push. Sevalla redeploys on push.
The filter box
Each category page has a filter that matches as you type. It tolerates typos and partial words ,
bookng finds the booking link document, audt finds the audits, by matching the letters
you typed in order, within a single word of the title. Groups with no remaining matches hide themselves,
so what is left on screen is only what is relevant.
It only searches titles, which is the reason titles have to be good. The site-wide search on the front page searches full document text as well.
Written September 2026, after the HubSpot category passed 50 documents.