Repository navigation
Voice and Writing
This page sets out how fiscalclock writes in its docs, README, release notes and error messages, with do and don't examples taken from the project.
Last reviewed: 1 Nov 2026
Voice is how a project sounds in writing; tone is how that voice adjusts to the place, such as a tutorial or an error message. fiscalclock's readers use its results for financial reporting dates, so every sentence has to be checkable and nothing may sound larger than its evidence. These rules apply the repository's evidence rules and the personality to writing. Use the words defined on the project Glossary, including its "Do not write" column.
In the examples below, a "Do" in quotation marks is real fiscalclock text and links its source. Every "Don't" is written for this page to show the contrast; none of it appears in the project.
| Rule | Do | Don't | Basis |
|---|---|---|---|
| British English | colour, organisation, licence, recognised | color, organization, license (as a noun), recognized |
cspell.json sets en-GB and disables the US dictionaries. |
The product name is always lowercase fiscalclock, even at the start of a sentence |
"fiscalclock is an open-source fiscal calendar engine." | "Fiscalclock is…", "FiscalClock", "Fiscal Clock" | The package name on crates.io, PyPI and npm, and every sentence of the README and AGENTS.md. |
| Sentence-case headings: capital only on the first word and on names | "Why you can check the results" | "Why You Can Check The Results" | Every heading in the README and on this wiki. |
| No superlatives or marketing words | "fiscalclock aims to be one open, data-defined engine whose answers are identical in Rust, Python and JavaScript." (README) | "The best-in-class, blazing-fast fiscal calendar library." | AGENTS.md evidence rule 5 |
| Narrow, defensible comparisons | "the crates.io search for "fiscal" found no 52/53-week or 4-4-5 calendar engine as of 31 Oct 2026" (PDR) | "The only fiscal calendar engine." | Evidence rule 5 |
| Cite a source or a reproducible check for every fact | "112 vector files with 4,070 cases in conformance/" with a link (README) |
"Thousands of tests." | Evidence rule 1 |
Write as of <date> for anything that can change |
"Status as of 31 Oct 2026" (Home) | "The latest version is 0.1.0." | Evidence rule 2 |
| Mark illustrative or unverified material where it appears | "It is an example, not a built-in: fiscalclock has no named calendars." (README) | An example definition with no label | Evidence rule 4 |
| Plain verbs | "fiscalclock tells you which fiscal year, quarter, period and week any date falls in" (README) | "fiscalclock empowers teams to leverage fiscal insights" | Evidence rule 5; personality |
| Say what is built and what is planned | "A command-line interface and an MCP server are planned for 0.4.0." (README) | "Comes with a CLI and MCP server." | Glossary: "built" and "planned" |
| Rule | Do | Don't | Basis |
|---|---|---|---|
Dates that are data (results, bounds, examples, table cells) are ISO YYYY-MM-DD
|
2023-01-29 (start, included) to 2024-02-04 (end_exclusive, excluded) |
1/29/23, 29/01/2023, Jan 29th |
spec/api-v1.md; trust research R8 |
| Give both bounds of a period, or the last day as well | "end_exclusive 2024-02-04, last_day 2024-02-03" |
"ends 2024-02-04" (which reads as inclusive) | ADR-0007 |
| Review and "as of" stamps in prose use day, short month and year | "Last reviewed: 1 Nov 2026" | "Last reviewed: 11/01/2026" | Current practice on every wiki page; see the open question below. |
| Thousands separators in prose counts | "4,070 cases" | "4070 cases" | README |
| Place | Tone | Do | Don't |
|---|---|---|---|
| Docs | Second person, task first, then the explanation | "You describe your organisation's fiscal calendar as a JSON definition, and fiscalclock tells you…" (Home) | "In this amazing guide we'll explore the exciting world of fiscal calendars!" |
| README | Fixed order that is easy to scan: what it is, status, packages, one example, why you can check the results, licence | "Status: 0.1.0 is the first release. The definition format and API are version 1 drafts and may change before 1.0" (README) | A hero slogan, a logo wall or badges that nothing computes (trust research) |
| Release notes | Keep a Changelog sections (Added, Changed, Fixed and so on), one fact per line, ISO date in the heading | "## [0.1.0] - 2026-10-31" then "Python package fiscalclock (CPython 3.10 and later, and free-threaded CPython 3.14)…" (CHANGELOG) |
"Huge release, lots of goodies inside!" with exclamation marks and emoji |
| Error messages | As the core writes them today: lowercase, no final full stop; the message says what is wrong and what was expected, the hint says what to do |
See the next section | "Error!", "Invalid input.", "Something went wrong" |
Every error is an object with a stable code from the error catalogue, a JSON path to the offending field, a message, a hint where one helps, and details (null or an object) (AGENTS.md design rule 7; spec/api-v1.md). The code and path are the contract; tests must not depend on the wording of message or hint.
The example from the spec:
{"code":"WEEKS_SUM_MISMATCH","path":"subdivision.periods","message":"periods sum to 51 weeks, expected 52","hint":"add one week to a period","details":null}| Part | Do (real text from the core) | Don't | Why |
|---|---|---|---|
code |
AMBIGUOUS_LABEL |
PARSE_ERROR, ERR_42
|
Codes name the condition, in upper snake case, and are listed in the catalogue in the same pull request that adds them. |
path |
subdivision.extra_week, label
|
"in your config" | A JSON path lets a person or a program go straight to the field. |
message |
"FY2026" matches 2 periods (AMBIGUOUS_LABEL, from calendar.rs) |
"Ambiguous input." | State the fact with the values involved. The label and count in this example are illustrative; the wording pattern is the core's. |
message with a reason |
"extra_week is missing, but every week-based rule produces 53-week years (71 in every 400 years)" (EXTRA_WEEK_MISSING, from definition.rs) |
"extra_week is required." | Say why the field is needed when the reason is not obvious. |
hint |
"pick one of the candidates, or make the templates distinct" (AMBIGUOUS_LABEL) |
"Please try again." | An imperative the reader can act on. |
hint for a type mistake |
"convert the timestamp to a date in the time zone you mean, then pass that date" (TIMESTAMP_REJECTED, from json.rs) |
"Dates only!" | Name the fix and the decision only the caller can make (which time zone). |
details |
AMBIGUOUS_LABEL lists every candidate, never picks one |
Silently returning the first match | ADR-0010; AGENTS.md design rule 8 |
fiscalclock is meant to be usable by software agents (PDR goal 5), and AI agents are one of its audiences (DD-002). Write about them the way you write about any other caller: say what they can call and what they get back.
| Do | Don't | Why |
|---|---|---|
"Every error has a stable code, a JSON path, a message, a hint where one helps, and details." (Agents-and-MCP) |
"AI-native error handling" | Names the actual feature. |
"explain returns the step-by-step rule trace for a date." (Glossary) |
"Agents understand your calendar." | Says what the operation returns, not what a model might do with it. |
| "The MCP server is planned for 0.4." (ADR-0013) | "Ready for agents" while the MCP server is not built | Built and planned are kept apart. |
| "software agents", "AI agents", "agents" | "agentic", "for the AI era", "AI-powered" | Slogans of this kind were found on peer sites and are on the list of clichés to avoid (peer analysis, research brief). |
fiscalclock computes its answers with fixed rules and reads no clock (ADR-0017); never imply that it uses a model or guesses.
| Avoid | Write instead |
|---|---|
| blazing, revolutionary, best-in-class, the only (AGENTS.md), seamless | A specific, sourced fact, or nothing |
| config, preset, calendar hash | definition, example definition, calendar_id (Glossary) |
| leverage, utilise, empower | use, help, let |
- None at present. Date style was settled by DD-028: ISO
YYYY-MM-DDin code, tables, results and diagrams; "1 Nov 2026" in running prose, including "as of" and "Last reviewed" stamps.
- AGENTS.md evidence rules
- Error catalogue in
spec/api-v1.md - Glossary for fiscal terms and words to avoid
- Brand-Foundation for the personality behind these rules
- Design-System, the hub for all design pages
fiscalclock is licensed under MIT OR Apache-2.0 (MIT, Apache-2.0). Last reviewed: 31 Oct 2026. Found an error on this page? Report it with the documentation form.