Немного оттопырю мизинчик и напомню вам о существовании Oxford Comma. Все иногда любят поспорить о её необходимости или об обратном, но мы то техрайтеры, в наших текстах не должна читаться двусмысленность, поэтому используем её примерно всегда, вот тут можно почитать/посмотреть чуть более длинный пост про это, enjoy:

https://medium.com/@kesiparker/how-to-use-the-oxford-comma-in-technical-writing-5d03bb39b966

#language #en

А почитайте (не сейчас, конечно, вечер пятницы, алло. В Pocket там закиньте.) как-нибудь про наречия, хороший пост на Quora:

https://www.quora.com/Why-are-adverbs-considered-evil-I-keep-hearing-eliminate-adverbs-as-a-piece-of-writing-advice

#language #en #resource

Ловите словарик терминологии на 1314 слов в plaintext формате. Сам словарь выкорчевали из Cybersecurity Style Guide, но подходит для всего около-IT'шного.

#tool #en #language

Есть в английском такой термин как weasel words, что на нашенском будет "обтекаемые выражения", это ни к чему не обязывающие слова, эдакая намеренная двусмысленность. Вы уже наверное поняли к чему я веду. В нашей работе не стоит злоупотреблять такими вещами (хотя иногда можно, когда хочется звучать почеловечнее, показать что вы слушаете, как на самом деле говорят "обычные люди"), всё это довольно таки серая зона, которую надо научиться чувствовать и использовать аккуратно и в меру.

Но чтобы уметь нащупывать этот момент и использовать его во благо, врага надо знать в лицо, так сказать "практиковать митридатизм".

Предлагаю к ознакомлению бессмертную классику прямиком из 1991 "Как отказаться от обтекаемых выражений" (🇺🇸)

Для упрощения жизни себе и другим, постарайтесь автоматизировать это не только в голове (да, это сложно, слишком много переменных нужно держать в уме) но и современными тулзами. В этом вам поможет или наш старый добрый правильно настроенный друг Vale или отдельно живущий write-good. И тот и другой можно настроить на проверку weasel words (и в качестве приятного бонуса можно даже включить подсказки E-Prime)

#language #en #testthedocs

Я уже не раз писал о том, как избавиться от passive voice в вашей документации и почти всегда привожу один и тот же трюк (с зомби).

И вот теперь наткнулся на онлайн-тулзу, которая немного упрощает эту работу и наглядно показывает, как оный трюк проворачивать. Полезность сомнительна, все это можно делать прямо в VS Code, но считаю не лишним еще раз вам напомнить, что количество passive voice на квадратный метр хорошо бы если не убрать, то уменьшить. Сам с этим борюсь с переменным успехом.

https://datayze.com/passive-voice-detector

#tool #language #testthedocs #en

У меня сейчас проходит небольшой цикл ревью очень маленьких кусочков текста (те самые microcopy) которые я писал довольно давно. И имею сказать, что усилия, требуемые, чтобы получилось ХОРОШО несоизмеримо выше усилий, которые нужно приложить, чтобы писать обычную (конечно же читабельную) документацию.

Очень согласен с этим твитом, can relate, так сказать:

https://twitter.com/krnswry/status/1283075386495074307

#resource #en #language

Немного о подсознательном восприятии.

Вчера наткнулся на вот такой вот твит: https://twitter.com/notdetails/status/1298349462440607750?s=19

Вообще довольно интересное наблюдение и явно проверенное опытом и временем, и кучей боли.

Самое время напомнить вам, что не все правила одинаково полезны и иногда куда полезнее нарушить правило, чем слепо слушаться. Мы же пишем для людей, и, соответственно, люди и будут это читать, а не компьютеры, которые не смогут распарсить текст, если там нет запятой или стоит парочка лишних.

Бонус треком - Lightning Talk с Write the Docs Portland 2020 как раз об уместности нарушения некоторых правил: https://youtu.be/HIfANztn_-A

#language #en #article

Мне очень нравится идея Plain English, и я планирую периодически вам об этом напоминать. Из plain ("простых") принципов Английского можно почерпнуть очень много полезного для нашей профессии, у них на сайте даже слоган: "Fighting for crystal-clear communications since 1979".

Чем это может быть полезно? Ну, например можно изучить конструкции построения приложения, брать наборы стоп-слов, которыми можно пополнить свои линтеры, чтобы они в будущем выдавали ворнинги. Можно настроить свою среду разработки так, чтобы она уведомляла вас, когда предложение становится "сложным" или же слишком длинным. Сотни профитов!

http://www.plainenglish.co.uk/how-to-write-in-plain-english.html

P.S Спешу заметить, что (по моему мнению, конечно) в современном техрайтинге одним plain English (то же самое применимо и к русскому) сыт не будешь. Можно сколь угодно "просто" и без ошибок писать, но без той самой доли "индивидуальности" документация и инструкции так и будут теми самыми бумажками, которые при покупке телефона или любой другой техники все выкидывают. Я бы хотел, чтобы документация была не только понятной, но и не унылой, как защита курсовой

#language #en

Не умеешь/не привык начинать с пустого листа? Застрял после первого предложения? Попробуй заставить Машин Лернинг (GPT-2) набросать идей!

Раньше я сам иногда пользовался Talk to Transformer, но он как-то совсем не очень. А сейчас наткнулся на writeup.ai и прям небо и земля.

Если где-то есть на пощупать что-то похожее но с GPT-3 — дайте знать в комментах.

#language #ai #en

Стоит ли использовать в документации обращение от первого лица множественного числа?

Наверняка во время написания технической документации, у вас возникала мысль использовать: “we”, “us”, и “ours”. Но в отличие от второго лица (“you”), использование “we” не так явно распространено или приемлемо.

Но не все так просто! Статья углубляется в вопрос использования “we” и кроме того, автор сравнивает как разные стайлгайды советуют поступать с вот этим вот всем.

🔗 Читать: Should you use the first-person plural in your documentation?

#language #en

👅 Языки:

#ru | #en

👷 Карьера:

#career — советы и всемозможные статьи о карьере техписателя
#conference — техписательские конференции, их записи и заметки
#resources — ресурс для саморазвития
#article — полезная статья, которая учит чему-то клёвому, что позволит стать более лучшим писателем
#vacancy — интересная вакансия или что-то связанное с наймом
#video — видео, видос, видосичек, видосюлька. И подкасты!
#book — книга/хендбук
#courses — курсы, программы для технических писателей

🛠 Технологии:

#tool — полезная утилита/приложение
#changelog — все о чейнджлогах, примеры, правила
#markdown — все о языке разметки Markdown
#reStructuredText — все о языке разметки reStructuredText
#asciidoc — все о языке разметки asciidoc
#LaTeX — все систему набора и вёрстки и язык разметки LaTeX
#ide — среды разработки и все что с ними связано
#vscode — все о Visual Studio Code, настройка, плагины, хитрости
#SSG — JAMStack, генераторы статических сайтов, Hugo, Jekyll, Antora, etc.
#testthedocs — тестирование документации, линтинг
#API — про документирование API, примеры, лайфхаки, подсказки
#diagram — про диаграммы (много про diagrams as a code), mermaid, UML
#screenshot — все про скриншоты, утилиты, сервисы и красивенькие фотоснимки экрана
#ai — про GPT, GitHub Copilot и прочее, где ИИ помогает нам писать

🧺 Общее:

#tonevoice — о правилах общения в документации
#language — что-то конкретно о языке, в основном английский
#legal — юридическая документация, лицензии
#styleguide — все о стилях и правилах
#DocsAsCode — все про подход к документации как к коду
#example — примеры документации (хорошие и плохие)
#uiux — интерфейсы, текст в интерфейсах, пользовательский опыт
#knowledgemanagement — менеджмент знаний, хранилища, тулзы, техники, советы и наблюдения
#versioning — про версионирование
#accessibility — все об аксессебилити в документации
#checklist — чеклист/шпаргалка
#vintage — винтажная документация, старые компьютеры, софт, техника, игры
#visual — про визуальную составляющую документации
#metrics — все о метриках документации
#random — что-то совсем косвенно относящееся к техписательству, юморески

Предлагайте новые хэштеги в комментариях!

У New Relic довольно неплохой стайлгайд по написанию документации. Отдельно хочу обратить внимание на 5 вопросов, которые авторы стайлгайда предлагают задать себе, чтобы понять то ли ты вообще делаешь.

Следующая секция стайлгайда “Writing inclusive content” учит как не ненароком не обидеть своего читателя. Она довольно базовая, поэтому предлагаю взглянуть на отдельную статью про настройку своего линтера, которая помогает как раз находить такие узкие места в вашей документации.

Читать:
[1] New Relic Style Guide + 5 questions
[2] Reducing negative and biased language in documentation

#testthedocs #styleguide #voicetone #en #tool #language