Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Jamulus Website - Agent Instructions

Content repo for jamulus.io. 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/` must go to `next-release` - it is the only tree that gets translated, and it has to wait for the translation sprint. Blog posts under `_posts/` and urgent build fixes go to `release`.
- Fill out the PR template checklist.
12 changes: 12 additions & 0 deletions contribute/en/Style-and-Tone.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ 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. The `AGENTS.md` file in the website repository points automated contributors here rather than repeating them, so this page stays the single source of truth.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
These guidelines apply to every contribution, including work drafted with AI assistance. The `AGENTS.md` file in the website repository points automated contributors here rather than repeating them, so this page stays the single source of truth.
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.


**Note:** It is very important to thoroughly proofread content before submitting it, as any corrections made later have a knock-on effect on translations.

<details markdown="1">
Expand Down Expand Up @@ -101,6 +103,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, but parts of it are read by tools as well. Keep the two apart.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we really need this destinction?

@pljones pljones Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think "Keep the two apart." is necessarily correct. I think telling people and AI tools here who the audiences are is useful - by why under "Punctuation" - it's a non sequeteur. That appropriate punctuation and layout can enable and improve reading by both audiences is probably also worth mentioning.

So maybe

Suggested change
Content here is written for people, but parts of it are read by tools as well. Keep the two apart.
Use of text layout, for example lists and punctuation, should aid the reader, whether a person or a tool.

@mcfnord mcfnord Jul 31, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure our audience wants to wrap its head around machines as readers. I think we agree that the gist of this concern is that SOMETIMES we're writing for a machine, and sometimes it's a human. When I write some code that will be pasted, that's for a machine, and it has real concerns about ASCII compliance. When we're writing for an HTML publication, we need to "code switch" and make sure the paste blocks are paste-ready. And the prose around them is for humans, and I will continue advocating for their richness as compared to machine-ready content.

Notice I didn't mention AI. I'm not sure this is about AI, here. AI can handle itself on the humanist of for-humans HTML.

Content here is written for people, and sometimes those people feed parts of it into machines. I think that's the central thrust intended here. Put that way, we should hit upon the ease of doing that with aides like click-to-copy, rather than select-and-copy, along with code width concerns (which need to work for both audiences).

I also believe this depth and nuance is better said to an agent, so maybe this guidance belongs in the repo AGENTS.md. I think perhaps we can let people submit PRs that are as sloppy as they want, and then just ask an agent to clean it up by these standards. Why educate people in this dead art? (And I have 25 years of professional experience in this particular dead art!)


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:
Expand Down
Loading