Если можете\умеете в английский на слух, тут вот неплохой подкаст на послушать по дороге домой вечерком. Ана Нельсон, техпис и создатель Dexy говорит об автоматазации тестирования док (кода в доках) и о всяком таком. Лишним не будет:
Ana Nelson: Writing Maintainable Code Documentation with Automated Tools and Transclusion
https://www.maintainable.fm/episodes/ana-nelson-writing-maintainable-code-documentation-with-automated-tools-and-transclusion
#video #testthedocs #en #article
Ana Nelson: Writing Maintainable Code Documentation with Automated Tools and Transclusion
https://www.maintainable.fm/episodes/ana-nelson-writing-maintainable-code-documentation-with-automated-tools-and-transclusion
#video #testthedocs #en #article
Иногда я всё-таки применяю в работе то, про что пишу. Теперь с удвоенной силой вам советую попробовать в работе линтер прозы Vale, и настроить его в качестве CI на проекте.
#testthedocs #tool #en
#testthedocs #tool #en
Сорян за бомбардировку постами, но не запощу щас — забуду, близится не самая простая неделя, а так лучше вброшу сегодня и потом посреди недели буду в панике искать чем вас еще интересным покормить.
———
Лавры Grammarly очевидно многим не дают спать спокойно.
Оно и не странно, задумка лежит на поверхности, в реализации не такая уж прямо скажем и сложная, а продукт, как и парикмахеры, был, есть и будет востребован всегда — теперь у нас есть Linguix. Умеет всё то же что и Граммарли, также просит деняг, проверяет слегка хуже. Дефолтный текст из Linguix проверенный им же самим и граммарли, выводы делайте сами.
А я скажу только одно: все эти ребятки занимаются не совсем тем, что было бы полезно нам с вами, техническим писателям. Да, Граммарли круто проверяет ошибки, доставляетпроёба пропущенные артикли и иногда даёт дельные советы, но нас в первую очередь интересуют другого рода правила. Давайте все вместе чаще пользоваться Vale, писать для него рулы, делиться ими, и заносить денег за Vale Server, он точно даст вам больше контроля над результатом. А при наличии кого-то, кто умеет в регулярные выражения — это просто палочка выручалочка. (но и грамарли тоже годная штука, шо уж тут)
#testthedocs #en #tool
———
Лавры Grammarly очевидно многим не дают спать спокойно.
Оно и не странно, задумка лежит на поверхности, в реализации не такая уж прямо скажем и сложная, а продукт, как и парикмахеры, был, есть и будет востребован всегда — теперь у нас есть Linguix. Умеет всё то же что и Граммарли, также просит деняг, проверяет слегка хуже. Дефолтный текст из Linguix проверенный им же самим и граммарли, выводы делайте сами.
А я скажу только одно: все эти ребятки занимаются не совсем тем, что было бы полезно нам с вами, техническим писателям. Да, Граммарли круто проверяет ошибки, доставляет
#testthedocs #en #tool
Linguix.com
Linguix — Grammar Checker and AI Writing App
Supercharge Your Written Communication with AI. Make your texts grammatically correct, clear, and highly effective on any website for free.
Карантин карантином, а хорошие новости по расписанию.
Microsoft рализит свою версию Grammarly под названием Microsoft Editor. Судя по последним маркетинговым роликам, где-то в недрах MS завелся офигенный моушн дизайнер, ролик с рекламой этого Editor'a ну очень красивый.
Обещают интеграцию со всем и вся: Word, Outlook, Браузер.
В перечне фишечек такое:
- Provides suggestions to improve sentence clarity
- Suggests alternate vocabulary
- Reminds you when to use formal language
- Supports over 20 languages
- A similarity checker helps catch plagiarism or lets you quickly provide citations if you’re the one writing
- Suggest alternative punctuation
- Suggest gender-neutral and inclusive terms to reduce inherent bias in writing
- Provide information on how long it takes to read or speak your document
#testthedocs #tool #en
Microsoft рализит свою версию Grammarly под названием Microsoft Editor. Судя по последним маркетинговым роликам, где-то в недрах MS завелся офигенный моушн дизайнер, ролик с рекламой этого Editor'a ну очень красивый.
Обещают интеграцию со всем и вся: Word, Outlook, Браузер.
В перечне фишечек такое:
- Provides suggestions to improve sentence clarity
- Suggests alternate vocabulary
- Reminds you when to use formal language
- Supports over 20 languages
- A similarity checker helps catch plagiarism or lets you quickly provide citations if you’re the one writing
- Suggest alternative punctuation
- Suggest gender-neutral and inclusive terms to reduce inherent bias in writing
- Provide information on how long it takes to read or speak your document
#testthedocs #tool #en
YouTube
Introducing Microsoft Editor: Write confidently across your Office apps and favorite websites
Learn more about Microsoft Editor: https://www.microsoft.com/en-us/microsoft-365/microsoft-editorBring out your best writer anywhere you write with Microsoft...
Есть в английском такой термин как weasel words, что на нашенском будет "обтекаемые выражения", это ни к чему не обязывающие слова, эдакая намеренная двусмысленность. Вы уже наверное поняли к чему я веду. В нашей работе не стоит злоупотреблять такими вещами (хотя иногда можно, когда хочется звучать почеловечнее, показать что вы слушаете, как на самом деле говорят "обычные люди"), всё это довольно таки серая зона, которую надо научиться чувствовать и использовать аккуратно и в меру.
Но чтобы уметь нащупывать этот момент и использовать его во благо, врага надо знать в лицо, так сказать "практиковать митридатизм".
Предлагаю к ознакомлению бессмертную классику прямиком из 1991 "Как отказаться от обтекаемых выражений" (🇺🇸)
Для упрощения жизни себе и другим, постарайтесь автоматизировать это не только в голове (да, это сложно, слишком много переменных нужно держать в уме) но и современными тулзами. В этом вам поможет или наш старый добрый правильно настроенный друг Vale или отдельно живущий write-good. И тот и другой можно настроить на проверку weasel words (и в качестве приятного бонуса можно даже включить подсказки E-Prime)
#language #en #testthedocs
Но чтобы уметь нащупывать этот момент и использовать его во благо, врага надо знать в лицо, так сказать "практиковать митридатизм".
Предлагаю к ознакомлению бессмертную классику прямиком из 1991 "Как отказаться от обтекаемых выражений" (🇺🇸)
Для упрощения жизни себе и другим, постарайтесь автоматизировать это не только в голове (да, это сложно, слишком много переменных нужно держать в уме) но и современными тулзами. В этом вам поможет или наш старый добрый правильно настроенный друг Vale или отдельно живущий write-good. И тот и другой можно настроить на проверку weasel words (и в качестве приятного бонуса можно даже включить подсказки E-Prime)
#language #en #testthedocs
Johns Hopkins University
How to eschew weasel words ...
The following story originally ran in the December 1991 issue of Johns Hopkins Magazine. The guidance below by Ronald Waters—former professor of history—and T.H. Kern, A&S '92, is so timeless we decided to publish it here.
Я уже не раз писал о том, как избавиться от passive voice в вашей документации и почти всегда привожу один и тот же трюк (с зомби).
И вот теперь наткнулся на онлайн-тулзу, которая немного упрощает эту работу и наглядно показывает, как оный трюк проворачивать. Полезность сомнительна, все это можно делать прямо в VS Code, но считаю не лишним еще раз вам напомнить, что количество passive voice на квадратный метр хорошо бы если не убрать, то уменьшить. Сам с этим борюсь с переменным успехом.
https://datayze.com/passive-voice-detector
#tool #language #testthedocs #en
И вот теперь наткнулся на онлайн-тулзу, которая немного упрощает эту работу и наглядно показывает, как оный трюк проворачивать. Полезность сомнительна, все это можно делать прямо в VS Code, но считаю не лишним еще раз вам напомнить, что количество passive voice на квадратный метр хорошо бы если не убрать, то уменьшить. Сам с этим борюсь с переменным успехом.
https://datayze.com/passive-voice-detector
#tool #language #testthedocs #en
Второй пост - комбинированный:
Избавляемся от нарочитых и подсознательных предвзятостей, опять же с помощью наших верных друзей - линтеров и засовываем Grammarly в VS Code
- Linter (вот так просто) на Руби (eww) помогает с inclusive language: gender-coded words, use of pronouns and misused words.
- Я когда-то давно писал о нём, но раз такое дело, то есть еще и linter-alex (alexjs)(в честь гендерно-нейтрального имени Саша), который делает почти то же самое.
- Кто-то захакал Grammarly прямо в VS Code, расширение конечно же сразу снесли с стора с экстеншнами, но еще можно скачать vsix файл, установить его в ручную и поклацать
#testthedocs #vscode #ide #tool #en
Избавляемся от нарочитых и подсознательных предвзятостей, опять же с помощью наших верных друзей - линтеров и засовываем Grammarly в VS Code
- Linter (вот так просто) на Руби (eww) помогает с inclusive language: gender-coded words, use of pronouns and misused words.
- Я когда-то давно писал о нём, но раз такое дело, то есть еще и linter-alex (alexjs)(в честь гендерно-нейтрального имени Саша), который делает почти то же самое.
- Кто-то захакал Grammarly прямо в VS Code, расширение конечно же сразу снесли с стора с экстеншнами, но еще можно скачать vsix файл, установить его в ручную и поклацать
#testthedocs #vscode #ide #tool #en
Есть такой сайтик, зовется goodui, на этом сайте постят примеры и результаты A/B тестирования крупнейших компаний: Amazon, Netflix, Airbnb, Etsy, Google и иже с ними.
Да, сайт посвящен в основном UI-решениям и паттернам, но и для нас, техписов, можно найти в этом ценность. Помимо того, что это просто дико интересно, т.к очень много информации на сайте берется из слитых скринов внутренней кухни, мы еще можем убедиться в пользе структурирования и упорядочивания всего и вся, и немного поучиться UX-райтингу у больших дядь.
На скрине к посту, например, пример эксперимента Amazon, где *кто бы мог подумать* структурированный и разложеный по полочкам контент оказался понятнее, читабельнее и впринципе приятнее глазу, чем полотно текста, которое выглядит автоматически сгенерированным, а-ля описания в Алиэкспресс.
#uiux #en #testthedocs
Да, сайт посвящен в основном UI-решениям и паттернам, но и для нас, техписов, можно найти в этом ценность. Помимо того, что это просто дико интересно, т.к очень много информации на сайте берется из слитых скринов внутренней кухни, мы еще можем убедиться в пользе структурирования и упорядочивания всего и вся, и немного поучиться UX-райтингу у больших дядь.
На скрине к посту, например, пример эксперимента Amazon, где *кто бы мог подумать* структурированный и разложеный по полочкам контент оказался понятнее, читабельнее и впринципе приятнее глазу, чем полотно текста, которое выглядит автоматически сгенерированным, а-ля описания в Алиэкспресс.
#uiux #en #testthedocs
Хорошие новости для пользователей oXygen XML Editor!
Начата работа по внедрению нативной поддержки Vale. Теперь следовать стайлгайдам будет проще
https://twitter.com/radu_coravu/status/1314460946417487873
#testthedocs #tool #en
Начата работа по внедрению нативной поддержки Vale. Теперь следовать стайлгайдам будет проще
https://twitter.com/radu_coravu/status/1314460946417487873
#testthedocs #tool #en
Twitter
Next version of @oxygenxml Terminology Checker add-on will support using Vale rules for checking. I just unleashed it on the Oxygen user's manual with the Microsoft style guide terminology vale rules, I wonder how our writers will react 😈
Vale теперь и в вебе!
Теперь для того, чтобы проверить ваш текст на соответствие с стайлгайдом (пока что Microsoft, Vale, и Write Good прибиты гвоздями, но скоро можно будет пользовать свои) не нужно настраивать ни CI, ни плагин для VS Code, теперь можно просто скормить сервису вебстранчку!
Doculint
Сервис пока находится на стадии бета-тестирования и требует некоторой шлифовки напильничком, но движение в правильном направлении уже есть. Пример подробного отчета на скрине к посту :}
#testthedocs #en #tool
Теперь для того, чтобы проверить ваш текст на соответствие с стайлгайдом (пока что Microsoft, Vale, и Write Good прибиты гвоздями, но скоро можно будет пользовать свои) не нужно настраивать ни CI, ни плагин для VS Code, теперь можно просто скормить сервису вебстранчку!
Doculint
Сервис пока находится на стадии бета-тестирования и требует некоторой шлифовки напильничком, но движение в правильном направлении уже есть. Пример подробного отчета на скрине к посту :}
#testthedocs #en #tool
Vale отлично справляется с md и adoc файлами, но что если у вас Swagger API дока, которая не хавается нативно линтером?
Vale & The OpenAPI Specification поможет разобраться именно в этом. API доки такие же доки как гайды и хау-ту, держите их в чистоте и порядке, и да будут ваши юзеры благодарны!
#asciidoc #markdown #testthedocs #en #tool
Vale & The OpenAPI Specification поможет разобраться именно в этом. API доки такие же доки как гайды и хау-ту, держите их в чистоте и порядке, и да будут ваши юзеры благодарны!
#asciidoc #markdown #testthedocs #en #tool
Начало недели, не очень хочется нагружать и себя, и вас чем-то совсем уж узкопрофильным, поэтому предлагаю слегка отвлечься и почитать небольшую историю о создании своего собественного статик сайт генератора, и о важности личных пет-проджектов.
Читать: Why I Built My Own Shitty Static Site Generator
Bonus Track: Микро-история про создание спеллчекера в 84 году (хотя больше про стремительный прогресс технологий)
#SSG #DocsAsCode #en #testthedocs
Читать: Why I Built My Own Shitty Static Site Generator
Bonus Track: Микро-история про создание спеллчекера в 84 году (хотя больше про стремительный прогресс технологий)
#SSG #DocsAsCode #en #testthedocs
🗞 Постоянные читатели этого канала могли заметить, что у канала временами имеется некий уклон в сторону автоматизации проверки стиля текста.
Так вот, сегодня как раз такой день когда я вам в очередной раз напоминаю, что линтер - отличное средство экономии времени и облегчения мозговой деятельности, которую можно направить в куда более полезное русло.
The Guardian рассказывает как они пришли к созданию своей версии проверялки статей на соответствие с внутренним руководством по стилю. И не просто рассказывают, а показывают и дают чуть-чуть потыкать и даже поконтрибьютить туда. На удивление достаточно техническая статья для новостного “портала”, и от того более интересная нам с вами. Да и вообще необычно видеть, как такие большие компании так хорошо рассказывают о своей внутрянке.
👀 Отдельно советую обратить внимание на их документ с Виденьем того, чем эта тулза должна быть и какими принципами руководствоваться.
Все, что у них получилось очень похоже на LanguageTool (он там частично и используется) + Vale Server, а это в очередной раз подтверждает, что все мы двигаемся в ± одном направлении и это очень даже здраво.
🔗 Читать: How we made Typerighter, the Guardian’s style guide checker
#testthedocs #en
Так вот, сегодня как раз такой день когда я вам в очередной раз напоминаю, что линтер - отличное средство экономии времени и облегчения мозговой деятельности, которую можно направить в куда более полезное русло.
The Guardian рассказывает как они пришли к созданию своей версии проверялки статей на соответствие с внутренним руководством по стилю. И не просто рассказывают, а показывают и дают чуть-чуть потыкать и даже поконтрибьютить туда. На удивление достаточно техническая статья для новостного “портала”, и от того более интересная нам с вами. Да и вообще необычно видеть, как такие большие компании так хорошо рассказывают о своей внутрянке.
👀 Отдельно советую обратить внимание на их документ с Виденьем того, чем эта тулза должна быть и какими принципами руководствоваться.
Все, что у них получилось очень похоже на LanguageTool (он там частично и используется) + Vale Server, а это в очередной раз подтверждает, что все мы двигаемся в ± одном направлении и это очень даже здраво.
🔗 Читать: How we made Typerighter, the Guardian’s style guide checker
#testthedocs #en
Если вы только начали открывать для себя линтеры простого нашего с вами языка, то предлагаю к ознакомлению отличный интродакшн в Vale.
Объясняют и в чем отличие от линтеров кода, и этимологию самого слова, и даже делятся ссылочкой на Vale Studio, которой я совсем забыл с вами поделиться. Vale Studio это бесплатный веб-бейзд редактор, который позволяет легко создавать и тестировать новые правила. Очень тесно интегрирован с regex101.
🔗 Читать: First steps with the Vale prose linter
#tool #testthedocs #en #article
Объясняют и в чем отличие от линтеров кода, и этимологию самого слова, и даже делятся ссылочкой на Vale Studio, которой я совсем забыл с вами поделиться. Vale Studio это бесплатный веб-бейзд редактор, который позволяет легко создавать и тестировать новые правила. Очень тесно интегрирован с regex101.
🔗 Читать: First steps with the Vale prose linter
#tool #testthedocs #en #article
Выходим из недельного застоя:
1. Статья о шести характеристиках хорошей докментации. Тут без откровений. Характеристик хорошей документации куда больше, но помнить об основе — надо
🔗Читать: Six characteristics of good docs
2. Если вы любитель «second brain» приложений а-ля Notion, есть большая вероятность, что вы уже открыли для себя Obsidian, про который я когда-то уже пару раз писал. Из подписчиков точно кто-то пользовался в компании. Так вот, для него вышел плашин с лучшим линтером простого, челвоеческого английского — Vale. Есть поддержка как и платной серверной версии, так и бесплатной CLI.
🔗 Читать: New plugin: Obsidian Vale
3. Из личного опыта. Писал тут когда-то про Mark — утилиту для синхронизации .md файлов с Clonfluence, которую можно запрячь в CI и вот это вот всё. Пост вызвал относительно бурную дискуссию и в том числе упрёки, что ничего там не работает. Добрался я таки до этой тулзы сам и имею сказать, что все работает. Пользоваться рекомендую Докер-образом и в качестве пароля передавать API-токен. Работает даже на Маке.
#ide #knowledgemanagement #en #testthedocs
1. Статья о шести характеристиках хорошей докментации. Тут без откровений. Характеристик хорошей документации куда больше, но помнить об основе — надо
🔗Читать: Six characteristics of good docs
2. Если вы любитель «second brain» приложений а-ля Notion, есть большая вероятность, что вы уже открыли для себя Obsidian, про который я когда-то уже пару раз писал. Из подписчиков точно кто-то пользовался в компании. Так вот, для него вышел плашин с лучшим линтером простого, челвоеческого английского — Vale. Есть поддержка как и платной серверной версии, так и бесплатной CLI.
🔗 Читать: New plugin: Obsidian Vale
3. Из личного опыта. Писал тут когда-то про Mark — утилиту для синхронизации .md файлов с Clonfluence, которую можно запрячь в CI и вот это вот всё. Пост вызвал относительно бурную дискуссию и в том числе упрёки, что ничего там не работает. Добрался я таки до этой тулзы сам и имею сказать, что все работает. Пользоваться рекомендую Докер-образом и в качестве пароля передавать API-токен. Работает даже на Маке.
#ide #knowledgemanagement #en #testthedocs
📓 В лучший линтер для прозы Vale по просьбам трудящихся завезли улучшенные метрики читабельности.
На трудность восприятия текста могут оказывать влияние следующие лингвистические особенности:
- длина слов и предложений,
- сложность синтаксических конструкций (наличие однородных членов предложения и предложно-падежных групп, перегруженность причастными и деепричастными оборотами),
- показатели частотности слова,
- уровень абстрактности лексики,
- обилие терминов
Эти метрики пусть и не сильно, но позволяют оптимизировать свои тексты. Следить за длиной предложений и их сложностью больше не нужно, теперь это можно поручить алгоритму.
Среди новых метрик:
- Automated readability index (ARI)
- Coleman–Liau
- Flesch–Kincaid
- Flesch reading ease
- Gunning fog
- LIX
- SMOG
🔗 Скачать: Vale-compatible implementations of many popular "readability" metrics
#testthedocs #en #tool
На трудность восприятия текста могут оказывать влияние следующие лингвистические особенности:
- длина слов и предложений,
- сложность синтаксических конструкций (наличие однородных членов предложения и предложно-падежных групп, перегруженность причастными и деепричастными оборотами),
- показатели частотности слова,
- уровень абстрактности лексики,
- обилие терминов
Эти метрики пусть и не сильно, но позволяют оптимизировать свои тексты. Следить за длиной предложений и их сложностью больше не нужно, теперь это можно поручить алгоритму.
Среди новых метрик:
- Automated readability index (ARI)
- Coleman–Liau
- Flesch–Kincaid
- Flesch reading ease
- Gunning fog
- LIX
- SMOG
🔗 Скачать: Vale-compatible implementations of many popular "readability" metrics
#testthedocs #en #tool
Вспомнилось тут в свете (надеюсь) скорого релиза IDE от JetBrains для техписателей, что есть кайфовый плагин для IntelliJ IDEA которым можно пользоваться уже сейчас.
Проверяет орфографию, грамматику и стиль, такой себе встроенный граммарли
🔗 Почитать больше о Grazie
#testthedocs #ide #en
Проверяет орфографию, грамматику и стиль, такой себе встроенный граммарли
🔗 Почитать больше о Grazie
#testthedocs #ide #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 — что-то совсем косвенно относящееся к техписательству, юморески
Предлагайте новые хэштеги в комментариях!
#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
Следующая секция стайлгайда “Writing inclusive content” учит как не ненароком не обидеть своего читателя. Она довольно базовая, поэтому предлагаю взглянуть на отдельную статью про настройку своего линтера, которая помогает как раз находить такие узкие места в вашей документации.
Читать:
[1] New Relic Style Guide + 5 questions
[2] Reducing negative and biased language in documentation
#testthedocs #styleguide #voicetone #en #tool #language
JetBrains в очередной раз очень сытно тизернули фичи грядущей IDE для технических писателей Writerside.
В этот раз — в самое сердечко, показали как работает встроенное тестирование документации: валидность разметки, целостность оглавления, ссылки и референсы, отпавшие картинки.
Не так давно я усиленно начал работать с AsciiDoc и решил, в виду более фичастого плагина, попробовать вернуться на WebStorm. И имею сказать, что забираю все претензии, которые имел к нему. За последние 4 или 5 лет, сколько я им не пользовался, вебшторм и все причастное к написанию в нем документации выросло до небывалых высот. Перешел с vscode и markdown на asciidoc+antora и webstorm, и не знаю бед.
В будущем канал сменит вектор с около-markdown штуковин и тулз на, как мне кажется, более зрелый и взрослый asciidoc, это моя новая любимая игрушка.
#markdown #asciidoc #tool #en #testthedocs
В этот раз — в самое сердечко, показали как работает встроенное тестирование документации: валидность разметки, целостность оглавления, ссылки и референсы, отпавшие картинки.
Не так давно я усиленно начал работать с AsciiDoc и решил, в виду более фичастого плагина, попробовать вернуться на WebStorm. И имею сказать, что забираю все претензии, которые имел к нему. За последние 4 или 5 лет, сколько я им не пользовался, вебшторм и все причастное к написанию в нем документации выросло до небывалых высот. Перешел с vscode и markdown на asciidoc+antora и webstorm, и не знаю бед.
В будущем канал сменит вектор с около-markdown штуковин и тулз на, как мне кажется, более зрелый и взрослый asciidoc, это моя новая любимая игрушка.
#markdown #asciidoc #tool #en #testthedocs