diff --git a/.agents/skills/accuracy-check.md b/.agents/skills/accuracy-check.md new file mode 100644 index 00000000000..7d1ae90913e --- /dev/null +++ b/.agents/skills/accuracy-check.md @@ -0,0 +1,52 @@ +# Accuracy check + +Go through a page and check that everything it claims is actually true in the +code. + +## Where to look + +- Anything about the web app, its screens, settings, or API: `OpenFn/lightning`. +- Anything about the CLI, deploying, `project.yaml`, or how job code is + compiled: `OpenFn/kit`. +- Anything about a specific adaptor's functions or credentials: + `OpenFn/adaptors`, under `packages//`. + +Use the main branch unless the page names a version. Write down which commit +you checked against. + +## Steps + +1. **List the claims.** Read the page and number every statement a reader + could act on: code samples, function names and arguments, button and menu + names, settings and their defaults, version numbers, file paths, limits. + Skip the motivational text and the "in v1 this used to be" notes. +2. **Check each one.** Find the code that backs it up and note the file and + line. For job code samples, run `openfn compile` to make sure they at least + compile. Only run commands that read; never deploy, delete, or hit a live + OpenFn instance. If a name is missing from the code, look at the git + history in case it was renamed. +3. **Mark each claim** pass, fail, or uncertain. Uncertain covers things you + cannot verify from code: values set per deployment, anything that needs a + running system, pricing, and policy. Those belong to the product team. +4. **Decide what to do about failures.** Fix it if the right value drops + straight into the sentence (a flag name, a default, a label). Suggest it if + the paragraph would need rewriting. Ask if you cannot tell whether the docs + or the code is the one that is wrong, and say which you suspect. + +## Generated adaptor pages + +The pages under `adaptors/packages/` are built from code comments in +`OpenFn/adaptors`. Do not edit them here. Instead, find the comment in +`packages//src/` and write up an issue: the page URL, the source file +and line, what the docs say, what the code does, and the corrected comment. +Put it in the PR under "Upstream issues". Only file it if the user asked you +to. + +If a hand-written overview page (`adaptors/.md`) repeats the same +mistake, fix that one normally. + +## What to report + +For each page: the commits you checked, how many claims passed, failed, or +were uncertain, a table of the claims with their evidence, and the findings +in the standard format. Apply your fixes, run Prettier, and run `yarn build`. diff --git a/.agents/skills/fresh-user-eval.md b/.agents/skills/fresh-user-eval.md new file mode 100644 index 00000000000..50f4b0a2ed9 --- /dev/null +++ b/.agents/skills/fresh-user-eval.md @@ -0,0 +1,59 @@ +# Fresh-user evaluation + +Read one page as if you had never heard of OpenFn, then try to do what it +says. The point is to find where a newcomer would get lost. Run this after the +accuracy check, so the facts are already right. + +## Steps + +1. **Read it cold.** Pretend you know what an API, a webhook, JSON, and a + terminal are, and nothing else. Do not follow links. Do not look at the + page's history. When you finish, write one sentence saying what the page + teaches and who it is for. If you cannot, that is your first finding. + +2. **Try to do it.** + - If it is a how-to, follow the steps. For anything in the web app, check + the button or screen really exists in the Lightning code. For CLI steps, + run the commands. + - If it explains a concept, explain it back in two sentences. Then think of + three questions a newcomer would ask and see if the page answers them. + - If it is a reference table, pick three rows and see if you could use each + one from its description alone. + + Every time you have to guess what a word means, cannot find what the page + points at, read a sentence two ways, need something the page assumed you + had, find the steps in the wrong order, or cannot tell whether you + succeeded, write it down. + +3. **Check your guesses** against the code or nearby pages. If you guessed + wrong, the page definitely needs that information. If you guessed right, it + probably still does. + +## Sorting the findings + +- **Fix**: one missing fact that fits in one sentence and that you have + verified. Add it. +- **Suggestion**: anything bigger, such as a new subsection, an example, or a + rewrite. Propose the text but do not add it. +- **Question**: you could not find the answer, or it depends on who the page + is for. + +Do not touch the tone or voice. + +## Scores + +Give two scores from 1 to 5, each with a one-sentence reason. + +- **Readability.** 5: understood everything on one read. 3: got the gist but + had to work at it. 1: could not follow it without outside knowledge. +- **Completeness.** 5: could finish the task from this page alone and knew + when I was done. 3: got there, but only by following links or guessing. + 1: the page does not actually say how to do it. + +## What to report + +What the page teaches, who it is for, what you tried, your findings in the +standard format, and the two scores. + +Do not evaluate the generated adaptor pages. Do not write a new page; if the +page a user needs does not exist, that is a job for gap analysis. diff --git a/.agents/skills/gap-analysis.md b/.agents/skills/gap-analysis.md new file mode 100644 index 00000000000..b95d1df7b59 --- /dev/null +++ b/.agents/skills/gap-analysis.md @@ -0,0 +1,69 @@ +# Gap analysis + +Work out what a section of the docs should cover but does not. Produce a +ranked list. Do not write the missing pages unless you are asked to. + +## Steps + +1. **List what the docs cover.** For every page in the section, note what it + explains, using the headings and tables. Also note where it links out to + other sections, and check those pages exist. + +2. **List what the product has.** Look at the part of the code that matches + the section. For the web app, that is the routes and screens in + `OpenFn/lightning`. For the CLI, read `packages/cli/src/cli.ts` and + `commands.ts` in `OpenFn/kit`; that is where commands are registered, and + it shows things `--help` hides. Use `openfn --help` only as a fallback if + the CLI happens to be installed. For job writing, look at what + `packages/common` exports in `OpenFn/adaptors`. For deployment, read + `DEPLOYMENT.md` and the runtime config in Lightning. + + If you cannot reach the repo you need, say so in the report and skip that + part. Do not fill the gap from memory. + +3. **Compare the two lists.** Before you call anything a gap, search the + whole docs folder, the articles, and the adaptor overviews. It might be + documented somewhere else. Search for the thing as a user would type it, + not the bare noun: "openfn metadata" settles the question in one hit, + while "metadata" matches twenty pages of ordinary prose. Label each gap + as one of: + - **Missing page**: nothing in the docs mentions it. + - **Partial page**: the right page exists but does not cover this. + - **Misplaced**: it is documented, but not where a user would look. + - **Stale**: it describes an old version. Hand these to the accuracy check. + + Also note anything the docs describe that the product no longer has. + +4. **Look for user evidence**, if you have access to it: issues on the docs + repo, the community forum, support channels, search analytics. Count how + often a topic comes up. Do not quote anyone. If you have no access, say so, + and do not make up demand. + +5. **Rank.** Score each gap from 1 to 5 on three things: how many users it + affects, how bad it is to be without it, and how much evidence you have + that people want it. Add those three up; that is the impact score, and + you sort by it. Separately, score how easy it is to write (5 means a + paragraph, 1 means a whole tutorial) and show it in its own column. Use + ease only to break ties. Folding it into the sum lets a trivial gap + nobody asked for outrank a genuinely undocumented feature. + +## What to report + +For each gap: its label, its impact score and ease score, what is missing, +your evidence, where it should go (which file, and where in the sidebar or +which heading), and a rough outline. Put the top ten in the PR description +and collapse the rest. + +The report is the deliverable. A normal run of this skill opens a PR with an +empty or near-empty diff and a long description. That is expected. + +## What you may change + +Only one thing: add a single sentence linking to a page that clearly already +covers the topic. Everything else is a suggestion. + +Thin generated adaptor pages are not gaps here; they are code-comment issues +for `OpenFn/adaptors`. If a feature is behind a feature flag, or a command is +deliberately hidden in code (for example a CLI command with `describe: +false`), it is not a gap. Do not propose documenting it. Note it and ask the +product team if it looks like it should be public. diff --git a/.agents/skills/lint.md b/.agents/skills/lint.md new file mode 100644 index 00000000000..d4fa4bd812b --- /dev/null +++ b/.agents/skills/lint.md @@ -0,0 +1,55 @@ +# Lint + +Run this first on any section. These are mechanical checks. Most of what you +find, you can fix on the spot. + +Before you start, read `glossary.yml` (the approved terms) and +`style-exceptions.yml` (things humans have told us not to flag). Skip any +finding that matches an exception. + +Do not lint the generated adaptor pages, the old v1 docs, or translations +marked human-reviewed. + +## What to check + +Only look at prose. Ignore code blocks, URLs, and front matter. + +1. **Terminology.** If a page uses a spelling listed under `variants` in the + glossary, replace it with the approved term. Always change "adapter" to + "adaptor". Fix. Multi-word terms can be split across a line break by + Prettier's wrapping, so match against text with newlines collapsed to + spaces. +2. **Headings.** No `#` headings in the body (the title comes from front + matter). No jumping from `##` to `####`. No two headings with the same + text. Fix. If a page mixes Title Case and sentence case, suggest a change + rather than making it, because headings double as link anchors. +3. **Internal links.** Every link to another docs page must work. The easiest + way to check is `yarn build`, which fails on broken links. Fix it if the + right target is obvious. Otherwise ask. +4. **External links.** Try each one twice. A 404 or 410 means it is dead. + Replace it if there is a clear replacement; otherwise suggest removing it. + A 403 or 429 does not mean dead, so leave those alone and note them. +5. **Orphan pages.** A page that is not in any sidebar and not linked from + anywhere. Suggest adding or removing it. Do not decide yourself; someone + might be drafting it. +6. **Front matter.** Must be valid YAML and must have a `title`. If the title + is missing, take it from the page's first heading. Fix. +7. **Code blocks.** Every fenced block needs a language: `js`, `json`, + `yaml`, `bash`, or `text`. Fix. +8. **Alt text.** Every image needs alt text that says what the image shows. + "Screenshot" does not count. Write it from the surrounding paragraph. Fix. +9. **Callouts.** `:::tip` and similar blocks need a blank line after the + opening and before the closing. Fix. + +## How to fix + +Change only the line with the problem. When you are done, run Prettier on the +files you touched, then `yarn build`. Do not commit until both are clean. + +## What to report + +Give the counts (files checked, fixes, suggestions, questions), then one line +per finding in the standard format. + +If a reviewer undoes one of your fixes, do not push back. Suggest they add an +entry to `style-exceptions.yml` so it is not flagged again. diff --git a/.agents/skills/release-review.md b/.agents/skills/release-review.md new file mode 100644 index 00000000000..5c6406f31f0 --- /dev/null +++ b/.agents/skills/release-review.md @@ -0,0 +1,80 @@ +# Release review + +Look at what the product shipped recently and make sure the docs caught up. +With no arguments, review every release in `OpenFn/lightning`, `OpenFn/kit`, +and `OpenFn/adaptors` from the last month. Someone can narrow it to one repo, +a date range, a release tag, or a single PR. + +This is the inverse of the accuracy check. That skill starts from a docs page +and looks for the code. This one starts from what changed in the code and +looks for the docs. + +## Two repos are involved + +The releases live in the product repos. The docs live here. You need both. + +- **Running in the docs repo** (the usual case): clone each product repo you + need into a scratch directory outside this one. Fetch tags. Do not modify + the product repos. +- **Running inside a product repo** (someone asks "did the docs keep up with + this release?"): clone `OpenFn/docs` into a scratch directory and do the + same work. Docs changes always go in a branch and PR on the docs repo. + +Say at the top of your report which repos, tags, and dates you covered. + +## Steps + +1. **Start from the changelogs, not the diffs.** Each repo keeps one: + Lightning has a single `CHANGELOG.md`; kit and adaptors have one per + package under `packages//CHANGELOG.md`. Read every entry released in + the period. These are already a curated list of user-facing changes, so + they are cheaper and more reliable than reading every PR. Skip the + Unreleased section; docs describe what has shipped. + +2. **Turn each entry into a plain statement of what changed for a user**: a + new feature, a renamed button, a new CLI flag, a changed default, a removed + option, a new setting. Drop entries that are internal (refactors, + dependency bumps, test changes). If an entry is too vague to act on, open + the PR it links to and read the diff. Only then. + +3. **Find the docs that talk about it.** For each change, search `docs/`, + `articles/`, and `adaptors/*.md` for the feature, the old and new names, + the flag, or the setting. Search for things the way a user would type + them ("openfn pull --beta", not "beta"). Note every page and line. + +4. **Decide what each page needs.** + - **Now wrong.** The docs describe the old behaviour. Fix it if the new + behaviour is clear and slots into the existing sentence. Otherwise + suggest wording. + - **Now incomplete.** The page is still right but does not mention the new + thing. Suggest where the paragraph or table row goes and draft it. + - **Nothing in the docs.** A new feature with no home. Suggest a page or + section and a short outline. Do not write the page unless asked. + - **Screenshot affected.** The change alters a screen that appears in an + image. List the image for the retake list. Never retake it. + + A feature behind a feature flag, or a command hidden in code, is not a + docs gap. Note it and ask the product team if it looks like it should be + public. + +## Adaptors are different + +Changes to adaptor functions flow into the docs automatically through the +generated reference pages, so you do not need to chase those. For adaptors, +ask only two questions: is there a new adaptor with no overview page in +`adaptors/`, and did a change break something a tutorial or guide relies on. + +## What to report + +Start with one paragraph: the repos and period covered, how many releases, +how many user-facing changes, and how many docs pages are affected. Then the +findings in the standard format, grouped by page. Finish with images that +need retaking and new pages that are needed. + +Apply the fixes, run Prettier and `yarn build`, and open a docs PR that links +to the releases it covers. Suggestions and questions go in the PR +description. If the period had no user-facing changes, say so and do not open +a PR. + +This skill suits a monthly schedule with default arguments, plus a manual run +after any large release. diff --git a/.agents/skills/screenshot-triage.md b/.agents/skills/screenshot-triage.md new file mode 100644 index 00000000000..91c58021432 --- /dev/null +++ b/.agents/skills/screenshot-triage.md @@ -0,0 +1,74 @@ +# Screenshot triage + +Find the screenshots most likely to be out of date and rank them so a human +can retake them. You never retake, edit, or delete an image yourself. + +By default, scan the whole repo. A ranking only means something across the +whole site. If the user names a page or section, limit the scan to the images +those pages use. + +You need a clone of `OpenFn/lightning` with full history, because the whole +method is about comparing dates. + +## Remembering what each image shows + +Keep a file called `screenshot-map.yml` at the repo root. For each image it +records what the image shows, which UI area that maps to, and how confident +you were. Read it at the start of every run. Only classify images that are +new, renamed, or missing from the file, then add them. Dates are always +recomputed; classifications are not. This makes a repeat scan of the whole +repo cheap. + +Humans can edit this file to correct a classification, and the correction +sticks. Put a short comment at the top explaining the format. + +## Steps + +1. **List the images.** For the whole repo, everything in `static/img/`, + noting any image no page uses. For a page or section, only the images + those pages link as `/img/...`. + +2. **Find out how old each image is** from its last commit in this repo. If + the last commit was a bulk optimisation that touched lots of images, look + at the one before it. + +3. **Work out what each image shows**, for images not already in + `screenshot-map.yml`. Use the file name, the alt text, and the paragraph + around it. Say how confident you are. Then match it to the part of the + Lightning code that draws that screen. Roughly: the workflow + canvas is under `assets/js/workflow-diagram`; the step editor, runs, + credentials, and project settings each have their own folder under + `lib/lightning_web/live/`; global styling is in `assets/css` and + `lib/lightning_web/components`. Screenshots of other products (Kobo, + DHIS2) have no matching code; mark them "external". + +4. **Find out when that part of the UI last changed.** Take the newest commit + touching the matching code, or the global styling, whichever is later. Skim + the commit messages since the image was taken and keep the ones that sound + visible to users (renamed, moved, redesigned, added a button). + +5. **Flag and rank.** An image is a suspect if the UI changed after it was + taken. Sort by the size of the gap, then by how many visible changes + happened in it, and give pages in Get Started and Tutorials a nudge up the + list. If you were not confident about what an image shows and it lands + near the top, say so. + +## What to report + +A table with: image, page and line, image date, what it shows and your +confidence, date of the last UI change, the gap in days, and what probably +changed. List external, unused, and diagram images separately. Put the top +fifteen in the PR and collapse the rest. + +Whole-repo scans are report-only apart from updating `screenshot-map.yml`. +When scoped to a page or section, you may also correct alt text that describes +an image wrongly. + +## Later: taking screenshots automatically + +Not built yet. Lightning already has Playwright browser tests under +`assets/test/e2e/specs/`. When those can produce screenshots, add a final +step: a mapping file that says which test reaches which screenshot, run the +test with a capture flag against a local Lightning, save the result over the +old image, and present the before-and-after in the PR as a suggestion for a +human to approve. diff --git a/.agents/skills/translate.md b/.agents/skills/translate.md new file mode 100644 index 00000000000..3e96a37082b --- /dev/null +++ b/.agents/skills/translate.md @@ -0,0 +1,107 @@ +# Translate + +Translate English docs into Spanish (`es`) and French (`fr`). The English is +always the source of truth. Translations are generated files that live in +this repo, in the `i18n/` folder, mirroring the path of the English page. + +Never translate the generated adaptor pages, the job library, or the old v1 +docs. + +## Before you start + +Check these three things. If any fails, stop and ask. + +- The locale is enabled in `docusaurus.config.js`. Do not enable it yourself; + that changes what gets deployed. +- `i18n/` is not in `.gitignore`. +- `glossary.yml` and `translation-rules.yml` are valid YAML. + +Translate the English page as it is on disk after any fixes and after +Prettier has run, so the hash you record matches what you translated. + +## Front matter + +Copy the English page's front matter. Translate only `title` and +`sidebar_label`. Then add: + +```yaml +translation_source_hash: +translation_review_status: machine +translation_model: +``` + +The hash is the content hash of the English file, from +`git hash-object docs/.md`, not a commit. Commits do not survive squash +merges: a hash pointing at a commit made on a branch dangles as soon as the +branch is squashed onto main. A content hash is the same wherever the file +lives, and it answers the only question the field exists to answer: is the +English still the version this was translated from? To compare, hash the +current English file and check it against the recorded value. + +`translation_review_status` can be `machine`, `needs-review`, or +`human-reviewed`. Only a human ever sets `human-reviewed`, and when they do +they also add `translation_reviewer` and `translation_review_date`. + +## Decide what to do with each page + +- **No translation yet.** Translate the whole page. +- **Translation exists, status is `machine` or `needs-review`.** Translate the + whole page again, but keep any fenced blocks (see below) exactly as they + were. +- **Translation exists but has no `translation_review_status`.** Treat it as + `machine` and regenerate it. +- **Status is `human-reviewed` and the hash matches the current English + file.** Skip it. It is up to date and approved. +- **Status is `human-reviewed` and the hash no longer matches.** Do not touch + the file. Recover the English the reviewer saw with + `git cat-file -p `, diff it against the current English, + translate only the changed parts, and open a separate PR with the proposed + diff for the named reviewer. If the old blob is no longer in the repo, + say so and offer a full retranslation as the suggested diff instead. + +## Fenced blocks + +A human can wrap part of a translation like this: + +```markdown + +Text a reviewer has corrected by hand. + +``` + +Copy those blocks into the new translation exactly, in the same place. If the +English they correspond to has been deleted, keep the block anyway and ask +what to do with it. + +## How to translate + +- Words in `glossary.yml` stay in English. For ordinary words that are also + product terms, like "run" or "step", keep the English only when the word + means the OpenFn thing. +- Follow any rules for the locale in `translation-rules.yml`. By default, + Spanish uses "tú" and French uses "vous". +- Copy code blocks and inline code exactly. You may translate comments inside + code. +- Keep the same structure: same headings at the same levels, same lists, + same callouts, same components. +- Add the locale to internal links (`/es/documentation/...`), except links + into the generated adaptor pages, which are English only. Give translated + headings the original English anchor so existing links still work. + +## Before you commit + +Check that the fixed glossary terms (the ones without `product_noun: true`, +such as OpenFn, Lightning, adaptor, webhook) appear as many times as in the +English. Product nouns like "run" and "step" are allowed to differ, since +their ordinary-English uses get translated. Before counting, join each file +into one line with single spaces: Prettier wraps prose at 80 columns, and +English and Spanish wrap at different points, so a multi-word term like "work +order" can sit across a line break in one file and not the other. Check the +code blocks are identical. Check the counts of headings, code blocks, +callouts, images, and tables match. Check the front matter is complete. Check +every fenced block survived. Then build that locale and make sure it passes. + +Open one PR per locale per section, separate from the English PR. Translated +files do not count toward the 20-file limit, because a section's translations +are reviewed as a set. If you spot a problem in the English while translating, +note it for the next English pass; do not fix it here. diff --git a/.gitignore b/.gitignore index a35029f4531..504d1673644 100644 --- a/.gitignore +++ b/.gitignore @@ -13,8 +13,7 @@ .docusaurus .cache-loader -# translation -/i18n +# translation: i18n/ is committed (translations are generated artefacts kept in-repo, see AGENTS.md) # Misc .DS_Store diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..4227d03cd0a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,117 @@ +# Docs maintenance agent + +You look after the OpenFn documentation site. It is a Docusaurus project. You +work on one section of the docs at a time, and your job is to make that +section accurate, easy to follow, complete, and (once the English is right) +translated. + +The detailed instructions for each job live in `.agents/skills/`. Each one +stands alone; read the one you need. + +## What you can and cannot edit + +**Edit freely** + +- Everything in `docs/`. This is the English source of truth. +- `sidebars-main.js`, which controls the navigation. +- The adaptor overview pages in `adaptors/*.md`. + +**Do not edit** + +- Anything in `adaptors/packages/` or `adaptors/library/`. These pages are + built automatically from code comments in the `OpenFn/adaptors` repo. If + something is wrong there, the fix belongs in that repo, not here. +- Anything in `versioned_docs/`. These are the old v1 docs and are frozen. + +**Ask before editing** + +- `docusaurus.config.js`, `package.json`, and anything in `.github/`. These + change how the site builds and deploys. + +**Special rules apply** + +- Translations in `i18n/`. See `translate.md`. +- The three rule files: `glossary.yml`, `style-exceptions.yml`, and + `translation-rules.yml`. Humans maintain these. Each explains its format at + the top. Only add an entry if the user asks you to. + +To check facts, you can read the product code. Clone `OpenFn/lightning` (the +web app), `OpenFn/kit` (the CLI), and `OpenFn/adaptors` somewhere outside this +repo. Never change them. + +## The order of work + +1. **Lint.** Fix formatting, links, headings, and terminology. +2. **Accuracy check.** Make sure every claim matches the code. +3. **Fresh-user evaluation.** Read the page as a newcomer and see if it works. +4. **Gap analysis.** Work out what is missing from the section. +5. **Screenshot triage.** Scans the whole repo by default; runs on request + rather than every time. +6. **Translate**, in its own PR per locale. + +If the user asks for one skill only, run that one and still finish with a PR. + +One skill runs from the other direction. **Release review** starts from what +the product shipped, by default every release in the last month, and finds +the docs pages that need to change because of it. Run it on a monthly +schedule, or by hand after a big release, or narrowed to one PR if someone +asks. + +## Pick one section + +A section is one category from the sidebar, one folder under `docs/`, or one +page. Never work on the whole site at once. If the user has not said which +section, stop and ask. List the sidebar categories to make choosing easy. + +## Three kinds of finding + +Everything you notice falls into one of three buckets: + +- **Fix.** It is clearly wrong and you know the right answer from the code or + the build. Make the change. Keep it small. Do not rewrite a page's voice or + structure and call it a fix. +- **Suggestion.** It is a judgement call. Do not change it. Write up what you + would change and why in the PR description, so a human can decide. +- **Question.** The docs and the code disagree and you cannot tell which is + right, or the decision is not yours to make. Do not guess. Ask. + +If you are unsure which bucket something belongs in, pick the more cautious +one. + +Write findings like this: + +``` +[fix] docs/build/triggers.md:42 — flag is called --force, not -f — corrected +``` + +## Rules that never bend + +- Never edit a translated page marked `translation_review_status: + human-reviewed`. Offer a diff instead. +- Never edit generated adaptor pages. Draft an issue for `OpenFn/adaptors` + and put it in the PR. Only file it if asked. +- Never retranslate text inside `` fences. +- Never translate a term listed in `glossary.yml`. +- Never retake, crop, or replace screenshots. +- Never disable a check to make the build pass. + +## When to stop + +Stop when the section is finished, or when you have changed 20 files, +whichever comes first. Then open a PR. Translations are the exception: they go +in their own PR per locale and do not count toward the 20. + +Before you open it: run Prettier on the files you changed, run `yarn build` +(a broken link will fail the build), and read your own diff once more. + +Use the PR template in `.github/`. Tick "I have used Claude Code". Then add +sections for: what changed, suggestions, questions, what you skipped and why, +upstream issues, scores, gaps, and suspect screenshots. Leave out any that +are empty. + +## House style + +- Every page has a `title` in its front matter. +- Internal links start with `/documentation/`, `/adaptors/`, or `/articles/`. +- Images live in `static/img/` and are linked as `/img/filename`. +- It is spelled **adaptor**, never "adapter". diff --git a/glossary.yml b/glossary.yml new file mode 100644 index 00000000000..f15f801eaa0 --- /dev/null +++ b/glossary.yml @@ -0,0 +1,194 @@ +# glossary.yml +# +# Purpose +# ------- +# Product vocabulary for the OpenFn docs. Two consumers read this file: +# +# 1. The translate skill (.agents/skills/translate.md). Any term with +# `translate: false` must appear verbatim in every translated page. +# 2. The lint skill (.agents/skills/lint.md). Any spelling in `variants` +# is flagged in English pages and replaced with `term`. +# +# Humans maintain this file. Add a term when a review shows the same +# correction being made more than once. +# +# Schema +# ------ +# terms: # list of glossary entries +# - term: string # canonical English spelling (required) +# translate: boolean # false = keep verbatim in all locales (default false) +# product_noun: boolean # true = the rule only applies when the word is used +# # as the OpenFn concept, not as ordinary English +# # (e.g. "run" the noun, not "run the command"). +# # Translators keep the product noun and may +# # translate the ordinary-English use. Default false. +# case_sensitive: boolean # true = lint flags case variants too (default false) +# variants: [string] # spellings lint should flag and replace with `term` +# note: string # guidance for humans and the agent +# locales: # optional. Only used when translate: true, to pin a +# es: string # specific rendering per locale instead of free +# fr: string # translation. +# +# patterns: # regexes that are never translated, for families +# - pattern: string # of identifiers too numerous to list (adaptor +# note: string # package names, CLI flags, env vars, ...) +# +# Matching is whole-word for `term` and `variants`. Code blocks, inline code, +# URLs, and front matter are always exempt from lint and translation. + +terms: + - term: OpenFn + translate: false + case_sensitive: true + variants: + - Open Fn + - Openfn + - openFn + note: The product and organisation name. Never localised. + + - term: Lightning + translate: false + case_sensitive: true + note: >- + The OpenFn web app (OpenFn/lightning). In user-facing docs prefer + "the OpenFn platform" or "the web app"; keep "Lightning" when the docs + refer to the repo or to self-hosting. + + - term: adaptor + translate: false + variants: + - adapter + - Adapter + note: >- + Always "adaptor", never "adapter". Also covers "adaptors", "Adaptor", + "Adaptors". Adaptor package names are matched by the pattern below. + + - term: workflow + translate: false + product_noun: true + note: >- + A Trigger plus Steps plus Paths configured on the Canvas or in + project.yaml. Keep "workflow" in translations when it names the OpenFn + object. + + - term: step + translate: false + product_noun: true + note: A unit of work inside a workflow. Was "job" in OpenFn v1. + + - term: job + translate: false + product_noun: true + note: >- + In v2 the job is the JavaScript expression a Step runs. Do not + "correct" v1 usage inside pages that are explicitly about v1 or + migration. + + - term: credential + translate: false + product_noun: true + note: Stored authentication configuration attached to a Step. + + - term: trigger + translate: false + product_noun: true + note: What starts a workflow. Types are webhook, cron, and kafka. + + - term: cron + translate: false + note: Trigger type and the scheduling syntax. + + - term: webhook + translate: false + note: Trigger type. One word, lower case, no hyphen. + + - term: run + translate: false + product_noun: true + note: >- + One execution of a workflow for a work order. Only the noun is + protected. "Run the CLI" is ordinary English and may be translated. + + - term: attempt + translate: false + product_noun: true + note: >- + Legacy name for a run. Do not replace it in migration or historical + pages. In pages about current v2 behaviour, prefer "run" and record the + change as a suggestion, not a fix. + + - term: work order + translate: false + variants: + - workorder + - work-order + note: The record created when a trigger fires; owns one or more runs. + + - term: project space + translate: false + note: Billing and hosting unit on the hosted OpenFn app. + + - term: project + translate: false + product_noun: true + note: Administrative grouping of workflows, credentials, and collaborators. + + - term: dataclip + translate: false + variants: + - data clip + - data-clip + note: A stored input or output state object. + + - term: collection + translate: false + product_noun: true + note: The Collections key-value store feature. Ordinary English use may be translated. + + - term: sandbox + translate: false + product_noun: true + note: A Lightning sandbox environment. + + - term: Canvas + translate: false + case_sensitive: true + note: The visual workflow editor in the web app. + + - term: Inspector + translate: false + case_sensitive: true + note: The step editing panel in the web app. + + - term: CLI + translate: false + case_sensitive: true + note: "@openfn/cli. Also keep every CLI command and flag verbatim." + + - term: state + translate: false + product_noun: true + note: >- + The `state` object passed between operations. Protected only when it + names the object (usually rendered in code as `state`). + + - term: operation + translate: false + product_noun: true + note: A function exported by an adaptor, e.g. `get()`, `upsert()`. + +patterns: + - pattern: "@openfn/[a-z0-9-]+" + note: npm package names (adaptors, CLI, runtime). + + - pattern: "language-[a-z0-9-]+" + note: Bare adaptor package names as they appear in the adaptor picker. + + - pattern: "\\bopenfn [a-z][a-z-]*" + note: CLI subcommands such as `openfn deploy`, `openfn pull`. + + - pattern: "\\b[A-Z][A-Z0-9_]{2,}\\b" + note: Environment variables and constants (OPENFN_API_KEY, WORKER_SECRET). + + - pattern: "\\bproject\\.yaml\\b" + note: The project state file name. diff --git a/style-exceptions.yml b/style-exceptions.yml new file mode 100644 index 00000000000..563597b2f44 --- /dev/null +++ b/style-exceptions.yml @@ -0,0 +1,43 @@ +# style-exceptions.yml +# +# Purpose +# ------- +# Lint findings that a human has rejected. The lint skill +# (.agents/skills/lint.md) loads this file and suppresses any finding that +# matches an entry, so the same rejected suggestion is not raised again. +# +# Humans maintain this file. Add an entry when you reject or revert a lint +# change in a PR and do not want it raised again. +# +# Schema +# ------ +# exceptions: +# - rule: string # lint rule id, one of: +# # terminology, heading-hierarchy, heading-case, +# # internal-link, external-link, orphan-page, +# # frontmatter, code-language, image-alt, +# # admonition-spacing +# scope: string # glob of files the exception applies to. +# # "**" = whole repo, "docs/jobs/**" = a section, +# # "docs/jobs/state.md" = one page. +# match: string # optional. Substring or regex the finding text must +# # contain for the exception to apply (e.g. a heading +# # text, a link URL, a term). Omit to suppress the whole +# # rule within the scope. +# reason: string # why the human rejected it. Required. +# added_by: string # GitHub handle +# added_on: string # ISO date (YYYY-MM-DD) +# source_pr: string # PR URL or number where the rejection happened +# +# Example +# ------- +# exceptions: +# - rule: heading-case +# scope: "docs/contribute/style-guide.md" +# match: "H1 - Create the best documentation" +# reason: The style guide intentionally shows every heading level. +# added_by: someone +# added_on: 2026-01-01 +# source_pr: https://github.com/OpenFn/docs/pull/000 + +exceptions: [] diff --git a/translation-rules.yml b/translation-rules.yml new file mode 100644 index 00000000000..07a70955629 --- /dev/null +++ b/translation-rules.yml @@ -0,0 +1,58 @@ +# translation-rules.yml +# +# Purpose +# ------- +# Locale-specific phrasing rules learned from human edits to machine +# translations. The translate skill (.agents/skills/translate.md) loads this +# file after glossary.yml and applies every rule whose `locale` matches the +# target locale. +# +# Glossary terms (never translate) belong in glossary.yml, not here. This file +# is for how to translate, not what to leave alone. +# +# Humans maintain this file. Add a rule when you correct a translation in a +# way that should apply to other pages too. +# +# Schema +# ------ +# rules: +# - locale: string # "es" or "fr" (or "*" for every locale) +# kind: string # one of: +# # term - a fixed rendering for a phrase +# # register - tone/voice guidance (formal vs informal "you") +# # punctuation - spacing, quotation marks, list punctuation +# # structure - how to handle headings, admonition titles, UI labels +# # avoid - a rendering the reviewer rejected +# source: string # English phrase or pattern the rule applies to (for +# # kind: term and avoid). Omit for global rules. +# target: string # required rendering (kind: term) or rejected rendering +# # (kind: avoid) +# instruction: string # plain-language rule the translator must follow +# example_source: string # optional English example +# example_target: string # optional translated example +# reason: string # why, in one sentence +# added_by: string # GitHub handle +# added_on: string # ISO date (YYYY-MM-DD) +# source_pr: string # PR URL or number where the edit happened +# +# Example +# ------- +# rules: +# - locale: es +# kind: register +# instruction: Address the reader as "tú", not "usted". +# reason: Matches the informal tone of the English docs. +# added_by: someone +# added_on: 2026-01-01 +# source_pr: https://github.com/OpenFn/docs/pull/000 +# - locale: fr +# kind: term +# source: "Save and Run" +# target: "Enregistrer et exécuter" +# instruction: UI button labels are translated to match the French UI strings in OpenFn/lightning. +# reason: Reviewer aligned button names with the app's own translations. +# added_by: someone +# added_on: 2026-01-01 +# source_pr: https://github.com/OpenFn/docs/pull/000 + +rules: []