«Технічне письмо за посібником Google» — брати чи ні

Що це насправді таке

Це набір інструкцій, які змушують модель писати документацію за стилем Google для розробників: активний стан замість пасивного, звертання на «ти», заголовки звичайним реченням, нумерований список для послідовності кроків, назви кнопок точно як на екрані, код — моноширинним, однозначні дати, альт-текст до картинок, без жаргону й порожніх слів.

Цільова робота скіла названа прямо в його описі: файли-описи проєктів, документація до інтерфейсів програм, коментарі в коді, посібники користувача.

Сам посібник Google опублікований під вільною ліцензією (Creative Commons Attribution 4.0) — тобто копіювати правила можна законно, вказавши джерело. Оновлений востаннє у квітні 2025.

Що в нас уже є

Три окремі набори правил письма, кожен зі своєю зоною:

• Як писати документ, який читає агент — контракт на початку, нуль «здогадайся сам», кожне речення або інструктує, або дає факт.
• Як звучить текст, що йде назовні — голос Юри, перелік ознак машинного письма, і обов'язковий рецепт наприкінці, без якого драфт не вважається готовим.
• Як тримати живі документи чистими — правити на місці, не лишати старе поруч із новим.

Плюс наскрізне правило чистої мови: називати кожну річ тим, чим вона є, без кодів і абревіатур.

Де дірка, а де конфлікт

Дірка справжня

Жоден із трьох наших наборів не каже, як влаштувати інструкцію для людини: коли нумерований список, а коли маркований, де стоїть попередження, як формулюється заголовок кроку. Тобто про «як воно звучить» у нас написано багато, про «як воно побудоване» — нічого.

Конфлікт теж справжній

Google радить «будь розмовним і дружнім», друга особа, американська англійська. Наше правило для вихідних текстів каже інше: жодної похвали, починай із відповіді, пиши мовою отримувача. Накладати правила Google на листи й повідомлення не можна — вони битимуться з тим, що вже вирішено.

Тому брати можна лише той шматок, що не перетинається: побудова покрокового тексту.

Чого в тебе немає взагалі

Більша частина скіла — про документацію для розробників. Я перевірив: у твоїх напрямках зараз таких текстів немає — ні описів проєктів, ні документації до інтерфейсів програм, ні посібників користувача. Отже, ця частина скіла була б куплена «на майбутнє», а не під наявну роботу.

Вісім правил, які варто взяти

1. Умова перед дією. Спершу «коли», потім «що зробити»: «Щоб зберегти — натисни…», а не «Натисни…, щоб зберегти».
2. Нумеровано = послідовність. Маркований список — тільки коли порядок не має значення.
3. Один крок — одна дія. Дві дії в одному пункті людина виконує наполовину.
4. Заголовок каже, що людина зробить, і пишеться звичайним реченням, не з Великих Літер.
5. Жодних «вище / нижче / зліва». На телефоні це просто неправда — називай місце словами.
6. Попередження стоїть перед кроком, якого стосується, а не після нього.
7. Назва кнопки — дослівно як на екрані. Переінакшена назва змушує людину шукати.
8. Дати й посилання однозначні. Не «03/04» і не «дивись тут».

Три варіанти й що я раджу

не раджу Поставити скіл як є

Плюс: нуль роботи. Мінуси: це четвертий набір правил письма з розмитою межею до трьох наявних — рівно те, що наші ж правила називають марною тратою уваги; більша частина його правил під роботу, якої немає; частина конфліктує з уже вирішеним; хто саме зібрав цей переказ — невідомо.

раджу Взяти вісім правил із першоджерела

Плюс: закриває справжню дірку, безкоштовно, з посиланням на джерело, без нового скіла й без конфлікту. Мінус: це моя ручна робота на пів години, і вісім правил — мій відбір, не Google-івський список.

теж чесно Не робити нічого

Плюс: нуль витрат. Мінус: наступного разу, коли система писатиме тобі інструкцію, вона знову побудує її навмання.

Найдешевша перевірка перед тим, як щось робити

Згадай один текст за останній місяць, який ти читав і який був би зрозумілішим за цими вісьмома правилами. Згадався — беремо. Не згадався — не беремо нічого, і це нормальна відповідь.

Я цю перевірку зробити за тебе не можу: вона про те, що дратувало тебе під час читання, а не про те, що видно у файлах.

Чого я не зміг перевірити

• Сама сторінка скіла не відкрилась — сайт відповідав відмовою через забагато запитів. Тому опис скіла я взяв із того, як цей сайт сам його описує в пошуку, а правила — з першоджерела Google. Дослівний текст інструкцій скіла я не бачив.
• Хто автор цього переказу — невідомо, як і те, чи є в нього своя ліцензія.
• Чи зібрався б колись у тебе фронт роботи з документацією для розробників — це твоє рішення, не факт із файлів.

Джерела

• Сторінка скіла на MCP Market — не відкрилась, опис узятий із пошукового викладу цієї ж сторінки.
• Посібник Google з документації для розробників — головні правила (Creative Commons Attribution 4.0).