diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..2b9d2a512 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,25 @@ +# Jamulus Website - Agent Instructions + +Content repo for jamulus.app. English is the source of truth: edits land in English first, then flow to other languages via Weblate/po4a. + +Read first: [README.md](README.md) (workflow, translation, branches) and the [Style and Tone guide](https://jamulus.io/contribute/Style-and-Tone) (voice, terminology, spelling). The guide governs; this file does not restate or override it. + +## Changes + +This is documentation, not code. The bar is: **is this better than what is there now?** Not complete, not final - better. A page that answers a reader's question one step sooner is worth submitting on its own. + +- One logical improvement per PR. Open several small PRs rather than one large one, and keep each reviewable. +- Never hold a documentation fix behind a code change. Pages ship on their own schedule. +- If you cannot tell whether your version is better, say so in the PR description instead of guessing. + +## Rules + +- Edit English source `.md` files only. Never hand-edit translated files or `.po` files - those belong to translators via Weblate. +- Plain ASCII (`-` `'` `"`) inside anything parsed or copy-pasted: code, CLI flags, URLs, frontmatter, dates, versions. Autocorrect and LLM output break this by default; check your diff. See the Punctuation section of the Style and Tone guide. +- British English spelling (colour, minimise, centre). + +## Submitting + +- Branch: `next-release` unless you have a reason. `release` is the live site and publishes immediately; `next-release` waits for the next release cutover. Anything under `wiki/en/` must go to `next-release` - it is the only tree that gets translated, and it has to wait for the translation sprint. Submit English only; the other languages are produced from it by translators. Blog posts under `_posts/` and urgent build fixes go to `release`. +- Fill out the PR template checklist. +- Disclose AI-generated text at the end of the PR description and of comments (e.g. `> 🤖 Used AI: , `). The person submitting remains the author and answers for every line. diff --git a/contribute/en/Style-and-Tone.md b/contribute/en/Style-and-Tone.md index 197d2d6b6..23bae065c 100644 --- a/contribute/en/Style-and-Tone.md +++ b/contribute/en/Style-and-Tone.md @@ -10,6 +10,12 @@ permalink: "/contribute/Style-and-Tone" While contributing to Jamulus or the website, you should also keep style and tone in mind. Have a look at the following guidelines. +These guidelines apply to every contribution, including work drafted with AI assistance. + +Note: The `AGENTS.md` file in the website repository points automated contributors here, so this page stays the single source of truth. + +As in the [Jamulus repository](https://github.com/jamulussoftware/jamulus/blob/main/CONTRIBUTING.md#ownership), the person who submits a change is its author and owner: understand and stand behind every line, and answer the questions reviewers direct at you. Disclose AI-generated text at the end of a pull request description or comment, for example `> 🤖 Used AI: , `. + **Note:** It is very important to thoroughly proofread content before submitting it, as any corrections made later have a knock-on effect on translations.
@@ -26,7 +32,7 @@ While contributing to Jamulus or the website, you should also keep style and ton ### Keep it concise and specific. {:.no_toc} -Avoid long-winded phrases and overly stylised language. Start simple, expand to details later, if at all ("inverted pyramid" style). +Avoid long-winded phrases and overly stylised language. Start simple, expand to details later, if at all. ### Be direct, but not demanding. {:.no_toc} @@ -41,7 +47,7 @@ Jamulus has users of varying skill levels ranging from complete beginner to audi ### Avoid using slang and euphemisms. {:.no_toc} -Jamulus is used around the world and translated in five languages (possibly more!). Use plain english to provide users and translators an easier understanding of our content. +Jamulus is used around the world and translated in many languages. Use plain english to provide users and translators an easier understanding of our content. ### Give solutions first. {:.no_toc} @@ -60,9 +66,6 @@ Informal English is preferred (e.g. "haven’t" not "have not". "Try to" not "Pl Try not to sound like a robot. Write conversationally, as if you were talking to a person. - - - ## Capitalisation and references Headings use sentence case "This is a heading" unless delineated (e.g. "Look - This is a heading"). @@ -101,6 +104,16 @@ Jamulus is "Free and Open Source (FOSS)" (not "free software" or "open source") "Server List" This is the list of Servers maintained by a Directory. A Server registers with a Directory to be _listed_ in that Directory’s _server list_. +## Punctuation + +Content here is written for people, and some of it gets pasted into tools: commands, paths, configuration. Punctuation that reads fine on the page can break once pasted. + +Inside anything a reader will copy or a tool will parse - code spans and fenced blocks, command-line flags, URLs, file paths, YAML frontmatter, HTML attributes, dates and version strings - use plain ASCII `-`, `'` and `"` only. A curly quote or a long dash pasted into a shell command, a config file or a search box is not the character the tool expects, and it fails in ways the reader cannot see. Word processors and AI writing tools insert those characters automatically, so check your work before submitting. + +In prose, plain ASCII is the safe default and most pages already use it. Where a typographic character genuinely helps the reader it is acceptable, but it is never required. Do not convert a page from one style to the other as a change of its own: that produces a large diff with no benefit to the reader, and churn for translators. + +When quoting a literal label from the app, reproduce it exactly, including any trailing dots ("File > Connection Setup..."). Do not correct a real menu label. + ## Units We use the following abbreviations: