Як написати пропозицію WebAssembly англійською мовою: Стандарти комітету мови
Посібник з шаблонами англійської мови, словниковим запасом і структурою документів, що використовуються у пропозиціях щодо стандартів WebAssembly — для інженерів, які беруть участь у W3C WebAssembly CG.
Писати для комітету з стандартів - це особлива майстерність
Документи стандартів займають унікальне місце в технічному письмі. Вони повинні бути достатньо точними, щоб служити як обов’язкові специфікації, достатньо ясними, щоб бути зрозумілими для реалізаторів на багатьох мовах і часах виконання, і достатньо переконливими, щоб побудувати консенсус серед людей з конкуруючими інтересами і думками.
WebAssembly Community Group (CG) і Working Group (WG) дотримуються конвенцій, спільних з іншими органами стандартів W3C і IETF. Якщо ви пропонуєте нову можливість або зміну у WASM, розуміння цих угод — і англійського регістру, який вони вимагають — так само важливо, як і технічний вміст.
Стандартна структура документів
Більшість пропозицій WebAssembly слідують спільній структурі. Кожен розділ має власні правила вибору слів.
1. Огляд / Вступ
У цьому розділі описано, що таке пропозиція і чому вона існує. Вона повинна бути зрозумілою для когось, хто не знайомий з мотивацією.
- Використовуйте теперішній час для опису поточного стану: “WebAssembly currently lacks a mechanism for…”
- Використовуйте майбутній час або умовний час для опису запропонованого стану: “Ця пропозиція вводить… / З цією зміною, програми будуть мати змогу…”
- Уникайте маркетингової мови. Не пишіть * « потужну нову функцію » * — пишіть * « механізм, який уможливлює X. » *
Мотивація
Розділ мотивації пояснює проблему, яку слід вирішити. Сильні мотиваційні розділи наводять реальні випадки використання і, де це можливо, докази попиту.
| Useful phrases | Usage |
|---|---|
| ”The absence of X forces implementations to…” | Describing the current workaround cost |
| ”This limitation prevents…” | Explaining blocked use cases |
| ”Several implementations have independently arrived at…” | Showing community convergence |
| ”User research indicates that…” | Evidence-based motivation |
Пропозиція
У цьому розділі міститься нормативний вміст — фактична зміна специфікації. Його мова дуже формалізована.
** Нормативні мовні конвенції:**
| Term | Meaning |
|---|---|
| ”MUST” | A requirement — non-compliance is an error |
| ”MUST NOT” | A prohibition |
| ”SHOULD” | A recommendation — deviation requires justification |
| ”MAY” | A permitted option |
| ”is defined to be” | Introduces a formal definition |
| ”is well-formed” | Satisfies the structural validity rules |
| ”traps” | Terminates execution with a runtime error |
| ”is implementation-defined” | Behaviour the specification intentionally leaves to implementers |
4. Розглянуті альтернативи
Цей розділ демонструє ретельне мислення і будує довіру комітету. Для кожної альтернативи:
- Зазначте, що це: “Альтернативним підходом було б…”
- Зазначте, чому він не був обраний: “Це було відхилено, тому що… / Цей підхід вимагав би… / Комітет визначив, що… ”
- Використовуйте нейтральну, невідкидаючу мову навіть для відкинутих альтернатив: “Хоча цей підхід має переваги, він вводить складність в…”
Відкриті запитання
Відкриті питання сигналізують про інтелектуальну чесність і запрошують внесок спільноти.
- Формуйте кожне питання точно: “Неясно, чи X повинно бути дозволено, коли Y також присутній.”
- Позначте питання за тим, хто повинен їх вирішити: “Це питання для членів CG, які зосереджені на безпеці.”
- Розрізняти питання, які блокують, і ті, які можна розв’ язати під час реалізації.
Реєстр стандартів
Стандартне письмо використовує формальну, безособову форму, яка відрізняється від повсякденного технічного письма.
Не робіть цього
-
Перша особа:
“Я думаю, що цей підхід кращий”→ “Цьому підходу віддають перевагу, тому що…” -
Неформальність:
“загалом”/“якось”/“ви б подумали, що…” -
Хеджування без субстанції:
“може бути, що…”→ “Є ризик, що…” -
Я хочу
-
Пасивний голос для опису поведінки специфікації: “Страта сигналізується, коли…”
-
Активний голос для визначення поведінки реалізатора: “The runtime must validate…”
-
Точне кількісне визначення: не “швидкий”, а “лінійний час у кількості інструкцій”
Участь у дискусіях комітетів
У зустрічах CG і гілках проблем, певні англійські шаблони повторюються.
| Situation | Phrase |
|---|---|
| Expressing concern | ”I have a concern about the interaction between this proposal and…” |
| Requesting clarification | ”Could the champion clarify the intended semantics when…” |
| Blocking a proposal | ”I would like to register a formal objection to…” |
| Expressing tentative support | ”I am broadly supportive of the direction, though I would like to see the alternatives section strengthened.” |
| Suggesting a revision | ”Would the authors consider amending the proposal to handle the case where…” |
Приклади висловлювань
-
- “Ця пропозиція вводить механізм для структурованого потоку керування через межі модулів, що вирішує обмеження, яке на даний час вимагає небезпечних обходів у компіляції мови.” *
- “Розділ мотивації повинен включати принаймні два конкретних випадки використання з доказами попиту від виробничих розгортань, а не гіпотетичних сценаріїв.”
- “Алтернатива з використанням нового операційного коду інструкції була розглянута, але відкинута на тій підставі, що вона вимагає змін до всіх існуючих перевіряючих без явної переваги над підходом типової системи.”
- “Відкрито питання, чи слід цю функцію заблокувати на прапорці можливостей або ввімкнути безумовно; комітет повинен вирішити це питання до того, як пропозиція перейде до Фази 3.”
- “Коли стек операндів порожній і зустрічається структурована інструкція керування, перевіряючий повинен повідомити про помилку типу — це не поведінка, визначена реалізацією.”
Практичні поради для ненароджених мовців
Документи стандартів переглядаються як рідними, так і нерідними носієм англійської мови. Граматичні помилки в нормативному тексті можуть створити справжню неоднозначність — “НЕ МОЖЕ” і “НЕ МІСЯЦЬ” мають різні значення, і відсутнє заперечення може звернути бажану вимогу.
Перед тим, як надіслати пропозицію, попросіть колегу прочитати нормативні розділи, особливо звертаючи увагу на неоднозначність у модальних дієсловах. Це поширене джерело запитів на редагування на стадії комітету.
Bytecode Alliance і W3C CG приймають внесок від всіх мовних середовищ. Якість вашого технічного розуміння важливіше, ніж рідна вільність. Ясна, точна, добре структурована англійська достатня — і досягається з практикою.
Розрізняють: мовлення для немовляти
Написання пропозиції WebAssembly для WebAssembly Community Group W3C (W3C Wasm CG) вимагає не тільки технічної експертизи, але і дуже специфічного типу письмового спілкування. Метою є ясність, стислість і формальність тону, що відображає спільну природу розробки стандартів. Для розробників, чия перша мова не є англійською, навігація у цьому середовищі може бути особливо складною. Легко впасти у фрази, які здаються надто розмовними або не мають точності, очікуваної в технічній пропозиції. Розглянемо деякі типові пастки і як активно їх вирішувати.
Однією з найчастіших проблем є використання нечітких слів, таких як « це повинно » або « нам потрібно ». У офіційному документі ці фрази не мають впливу і не передають * чому * за пропозицією. Замість того, щоб сказати « Це має бути ефективніше », що залишає місце для інтерпретації, спробуйте написати щось на зразок « Запропонована реалізація вводить складність O( n^2) у основний алгоритм; ми пропонуємо дослідити альтернативні підходи, які використовують таблицю гешів для досягнення очікуваної складності за час O( n) ». Зауважте чітке визначення проблеми (O( n^2)) і розв’ язання (таблиця гешів). Аналогічно, уникати «ми думаємо» - замінити його на «На основі нашого аналізу…» або «Ми пропонуємо…». Інша ключова область - активний проти пасивного голосу. В то время как пассивный голос не является по сути плохим, чрезмерная зависимость может создать запутанные предложения. Намагайтеся досягти балансу; активно заявляючи, хто відповідальний, коли це необхідно («Команда розслідує…») додає ясності і підзвітності.
Давайте поглянемо, як це може відбуватися в практичному сценарії. Уявіть, що ви надсилаєте запит на витяг (PR) до сховища W3C Wasm TC, описуючи зміну, пов’ язану з керуванням пам’ яттю. Колега може надіслати вам коментар на Slack: «Все виглядає добре, але, можливо, треба додати деякі деталі?» Це цілком зрозуміле відчуття, але воно не пропонує конструктивного зворотнього зв’язку. Краще було б сказати щось на зразок: “Дякую за відгук. Я додав докладне пояснення причин цієї зміни, зокрема, щодо потенційних проблем з фрагментацією пам’ яті, описаних у розділі 3. 2 специфікації. Це демонструє увагу і негайно звертає увагу на відповідну документацію. Пам’ ятайте, що кожне речення має безпосередньо сприяти передачі інформації і переконувати аудиторію - будьте обдуманими з вибором слів.
Нарешті, зверніть увагу на формулювання під час обговорення існуючих пропозицій або специфікацій. Замість того, щоб сказати « Це схоже на … », ефективніше буде сказати « Це базується на концепціях, описаних у RFC 9186 щодо синхронізації моделі пам’ яті ». Таким чином ви покажете, що виконали домашнє завдання і зрозуміли ширший контекст. Використання точної мови, зосередження уваги на * впливі *, а не просто на заяві того, що ви хочете, і посилання на існуючу документацію — це всі критичні компоненти успішного спілкування у середовищі розробки стандартів.