From a4e76957edf29acab65259fa6237722f238ec570 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:51:15 +0000 Subject: [PATCH 1/3] =?UTF-8?q?=EC=8B=9C=EC=9E=91=20=E2=80=94=20=EA=B8=80?= =?UTF-8?q?=ED=88=AC=20=EB=AC=B8=EC=84=9C(docs/voice.md=C2=B7docs/voice-ba?= =?UTF-8?q?nned.txt)=EB=A5=BC=20=EC=93=B4=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01KBjxwhdLKoNyn28YLnUz8x From b835d57d6bf4cab1b0c8e3655b3eca39a2ade874 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:58:56 +0000 Subject: [PATCH 2/3] docs: write the project voice down in voice.md, and start voice-banned.txt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit voice.md describes the voice the README and the build guide already use (rfc-cleanup.md §2.13, answer 6); voice-banned.txt starts with the §2.10 list. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01KBjxwhdLKoNyn28YLnUz8x --- docs/voice-banned.txt | 34 ++++++++++++++++++ docs/voice.md | 84 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 docs/voice-banned.txt create mode 100644 docs/voice.md diff --git a/docs/voice-banned.txt b/docs/voice-banned.txt new file mode 100644 index 00000000..e0a9a4c6 --- /dev/null +++ b/docs/voice-banned.txt @@ -0,0 +1,34 @@ +# Words and phrases that do not go into anything a person reads here. +# Why: docs/voice.md. The rule: docs/rfc-cleanup.md §2.10. +# +# One entry per line, written as it would appear in a sentence. Case does not +# matter. An English entry matches whole words, so "here's" does not catch +# "there's", and covers the word's other forms ("ensure" catches "ensures" +# and "ensuring"). A Korean entry matches anywhere in the text. A line that +# starts with # is a comment. +# +# check:voice (scripts/voice-lint.ts) reads this file. Adding a word needs no +# change to the script. + +seamless +robust +leverage +comprehensive +streamline +empower +cutting-edge +ensure +utilize +delve +it's important to note +here's + +효율적으로 +원활하게 +강력한 +최적화된 +혁신적인 +다양한 +전반적으로 +참고로 +살펴보겠습니다 diff --git a/docs/voice.md b/docs/voice.md new file mode 100644 index 00000000..a3db3aa3 --- /dev/null +++ b/docs/voice.md @@ -0,0 +1,84 @@ +# Writing voice + +The README and the build guide set the voice for everything else written +here. Read a page of [README.md](../README.md) and of +[BUILD_GUIDE.md](../BUILD_GUIDE.md) before writing anything longer than a +sentence. Where the two differ, write like the README. It was rewritten in +October 2026 and joins its clauses with colons and full stops; the build guide +still reaches for dashes and opens its callouts with an emoji. + +## Name the thing + +Not "the power input" but "`J4`, the screw terminal". Not "a lot of LEDs" +but "8,192 points of light". A wait is "about two minutes" and a deadline is +"15 October 2026". A number carries its unit, and when it helps, the thing it +is measured against: + +> it holds the panel to a 2.4 A budget, the high-power USB-A rating, so a +> white-out frame lands at roughly half brightness instead, while an ordinary +> bright pattern (~1.9 A) never notices. + +Part numbers and designators are written as the BOM writes them: +`PEC11R-4220F-S0024`, `C11`. A knob gets its place the first time: "K2, the +top-left knob". + +## Say what happens + +The guides say what the reader will see, and what it means when it looks +wrong: "The dialog usually ends without asking for it, and nothing failed: +close it." A limit is stated as one, even after a fix: "1/120 and slow motion +still band". A claim comes with what it rests on: "In testing, a +40,000 mAh bank dropped about 13% over 2 hours at full brightness, which is +roughly 15 hours on a full charge". "Usually" appears where it is true and +the reader can act on it, not as a cushion under every sentence. + +## Short, and finished + +Sentences carry one point each. A long one is followed by a short one, and a +short one can open a section by itself: "Two licenses, in two separate +files." A step starts with what to do and then says why: "Buy the LED panel +the BOM links. It's verified, and the case is measured around its screw +holes." The reader's situation becomes a question with the answer straight +after it: "No printer?" A paragraph covers one thing and stops when it is +said. Nothing at the end of a section repeats the section. + +## Who is speaking + +"You" is the reader. "We" is everyone who makes Patternflow: "Every +Patternflow plays every pattern we make." "I" is SeungHun Lee, only on a page +that already speaks as him, and only for something he does: "I'll add your +pin to the build map." New text never gives him a memory or a feeling he did +not write himself. + +## Words with fixed meanings + +[EDITIONS.md](EDITIONS.md#the-three-words) defines the words for firmware +builds, and prose uses them as defined there. A bundle is a composition's +folder and nothing more; "addon" and "variant" stay only where they name the +wire. The other nouns (core, preset, module, pack, deck, the console) mean +what the README uses them for, with no synonym swapped in. Brand spelling is +hard rule 4 in [AGENTS.md](../AGENTS.md). + +## Korean + +Korean text keeps the ending its file already uses: the web guide speaks +해요체 and [SERVICES.md](SERVICES.md) 합니다체. The habits above hold in both. + +## Side by side + +A sentence that reads as generated, then the one the docs have instead: + +> Make sure to select the correct USB port, as using the wrong one may cause +> problems during setup. +> +> Use its left port, labelled `USB` (antenna up, ports toward you): the right +> one flashes too, but the Wi-Fi step never appears there. + +> 부품을 준비하는 과정에서는 여러 가지 사항을 고려하는 것이 좋습니다. +> +> 전부 부품 목록에 있어요. 주문부터 해요. 배송이 제일 오래 걸려요. + +Words that never go in are in [voice-banned.txt](voice-banned.txt), one per +line. The maintainer adds to it, and `check:voice` reads it from there once +it lands ([rfc-cleanup.md §2.10](rfc-cleanup.md#210-writing-voice)). A +sentence that needs one of them to stand up is a sentence to cut. From 81df2472a9b86cba24bf32093a3cd0e96d888c7e Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 23:31:05 +0000 Subject: [PATCH 3/3] =?UTF-8?q?=ED=95=9C=EA=B5=AD=EC=96=B4=20=EA=B8=B0?= =?UTF-8?q?=EC=A4=80=EC=9D=84=20=EC=9B=B9=20=EA=B0=80=EC=9D=B4=EB=93=9C?= =?UTF-8?q?=C2=B7=EC=9D=BC=EC=A7=80=20=EB=8C=80=EC=8B=A0=20=EA=B3=B5?= =?UTF-8?q?=EA=B0=9C=20=EC=9C=A4=EB=AC=B8=20=EC=A7=80=EC=B9=A8=EC=9C=BC?= =?UTF-8?q?=EB=A1=9C=20=EB=B0=94=EA=BE=B8=EA=B3=A0,=20=EA=B0=80=EC=9D=B4?= =?UTF-8?q?=EB=93=9C=20=EB=AC=B8=EC=9E=A5=EC=9D=80=20=EB=B2=88=EC=97=AD?= =?UTF-8?q?=EC=B2=B4=20=EC=98=88=EB=A1=9C=20=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs: voice.md's Korean section no longer takes the web guide's Korean as its model. It lists the marks of carried-over Korean from two published Korean editing skills and the KatFishNet study, and shows two of the guide's lines beside a version written in Korean first. The English sections are trimmed to keep the page to one page. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01KBjxwhdLKoNyn28YLnUz8x --- docs/voice.md | 81 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 30 deletions(-) diff --git a/docs/voice.md b/docs/voice.md index a3db3aa3..b4da5b23 100644 --- a/docs/voice.md +++ b/docs/voice.md @@ -1,36 +1,31 @@ # Writing voice -The README and the build guide set the voice for everything else written -here. Read a page of [README.md](../README.md) and of -[BUILD_GUIDE.md](../BUILD_GUIDE.md) before writing anything longer than a -sentence. Where the two differ, write like the README. It was rewritten in -October 2026 and joins its clauses with colons and full stops; the build guide -still reaches for dashes and opens its callouts with an emoji. +The README and the build guide set the voice for English here. Read a page of +[README.md](../README.md) and of [BUILD_GUIDE.md](../BUILD_GUIDE.md) before +writing anything longer than a sentence. Where the two differ, write like the +README: it has no dash between clauses and no emoji callout, and the build +guide still has both. Korean has a standard of its own, at the end. ## Name the thing Not "the power input" but "`J4`, the screw terminal". Not "a lot of LEDs" -but "8,192 points of light". A wait is "about two minutes" and a deadline is -"15 October 2026". A number carries its unit, and when it helps, the thing it -is measured against: +but "8,192 points of light". A number carries its unit, and when it helps, +the thing it is measured against: > it holds the panel to a 2.4 A budget, the high-power USB-A rating, so a > white-out frame lands at roughly half brightness instead, while an ordinary > bright pattern (~1.9 A) never notices. -Part numbers and designators are written as the BOM writes them: -`PEC11R-4220F-S0024`, `C11`. A knob gets its place the first time: "K2, the -top-left knob". +A part is named as the BOM names it (`PEC11R-4220F-S0024`), and a knob gets +its place the first time: "K2, the top-left knob". ## Say what happens The guides say what the reader will see, and what it means when it looks wrong: "The dialog usually ends without asking for it, and nothing failed: close it." A limit is stated as one, even after a fix: "1/120 and slow motion -still band". A claim comes with what it rests on: "In testing, a -40,000 mAh bank dropped about 13% over 2 hours at full brightness, which is -roughly 15 hours on a full charge". "Usually" appears where it is true and -the reader can act on it, not as a cushion under every sentence. +still band". "Usually" appears where it is true and the reader can act on it, +not as a cushion under every sentence. ## Short, and finished @@ -38,9 +33,7 @@ Sentences carry one point each. A long one is followed by a short one, and a short one can open a section by itself: "Two licenses, in two separate files." A step starts with what to do and then says why: "Buy the LED panel the BOM links. It's verified, and the case is measured around its screw -holes." The reader's situation becomes a question with the answer straight -after it: "No printer?" A paragraph covers one thing and stops when it is -said. Nothing at the end of a section repeats the section. +holes." A paragraph covers one thing and stops when it is said. ## Who is speaking @@ -55,18 +48,11 @@ not write himself. [EDITIONS.md](EDITIONS.md#the-three-words) defines the words for firmware builds, and prose uses them as defined there. A bundle is a composition's folder and nothing more; "addon" and "variant" stay only where they name the -wire. The other nouns (core, preset, module, pack, deck, the console) mean -what the README uses them for, with no synonym swapped in. Brand spelling is -hard rule 4 in [AGENTS.md](../AGENTS.md). - -## Korean - -Korean text keeps the ending its file already uses: the web guide speaks -해요체 and [SERVICES.md](SERVICES.md) 합니다체. The habits above hold in both. +wire. Brand spelling is hard rule 4 in [AGENTS.md](../AGENTS.md). ## Side by side -A sentence that reads as generated, then the one the docs have instead: +A sentence that reads as generated, then the one the README has instead: > Make sure to select the correct USB port, as using the wrong one may cause > problems during setup. @@ -74,9 +60,44 @@ A sentence that reads as generated, then the one the docs have instead: > Use its left port, labelled `USB` (antenna up, ports toward you): the right > one flashes too, but the Wi-Fi step never appears there. -> 부품을 준비하는 과정에서는 여러 가지 사항을 고려하는 것이 좋습니다. +## Korean + +Korean keeps the ending its file already uses (해요체 or 합니다체) and reads +as if it was written in Korean first. Everything above holds in Korean too. +Neither the journal nor the web guide is the model. The journal is a diary, +and the guide's Korean was carried over from its English sentence by +sentence. The marks of carried-over Korean, as two published Korean editing +skills list them (DaleSeo's +[humanizer](https://github.com/DaleSeo/korean-skills/tree/main/skills/humanizer) +and epoko77-ai's [Humanize KR](https://github.com/epoko77-ai/im-not-ai)): + +- English prepositions turned into particles: `~에 대해`, `~를 통해`, + `~에 있어서`, `~에 의해`. The plain particle or the verb says it. +- An English verb on a subject that is not a person. "드라이버 IC가 + 결정해요" is "the driver IC decides". +- `가지고 있다` for have, and `~되어지다` for a passive that `~되다` + already is. +- `~할 수 있다` where the sentence can simply say the thing. +- A noun doing a verb's work: `확인을 진행해요` for `확인해요`. +- Pronouns and plurals the sentence does not need: `그`, `그것`, `이러한`, + `-들`. +- A comma wherever English would put one. Korean uses fewer + ([KatFishNet](https://aclanthology.org/2025.acl-long.1030/), ACL 2025). + +Two of the guide's lines in English and in Korean, then the same thing +written in Korean: + +> Its driver IC decides, not “HUB75E” in the title. +> +> 제목의 ‘HUB75E’가 아니라 드라이버 IC가 결정해요. +> +> 패널이 켜질지는 제목의 ‘HUB75E’가 아니라 드라이버 IC에 달려 있어요. + +> Take $100 as the floor, not the estimate +> +> 100달러는 예상치가 아니라 바닥이에요. > -> 전부 부품 목록에 있어요. 주문부터 해요. 배송이 제일 오래 걸려요. +> 100달러는 아무 문제 없이 끝났을 때 드는 돈이에요. 보통은 더 들어요. Words that never go in are in [voice-banned.txt](voice-banned.txt), one per line. The maintainer adds to it, and `check:voice` reads it from there once