This media is not supported in your browser
VIEW IN TELEGRAM
❓ Не совсем по теме документации, но обнаружена офигенная аппка на мак — Fig (https://fig.io/) добавляет VSCode-лайк автокомплит всем командам в терминале.
Соответственно вопрос, стоит ли делиться годными штуками, которые не сильно и связаны с докумментацией, но косвенно помогут в ее создании?
Соответственно вопрос, стоит ли делиться годными штуками, которые не сильно и связаны с докумментацией, но косвенно помогут в ее создании?
❤2
📓 В лучший линтер для прозы 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
❤1
👀 Интересный взгляд на Season of Docs 2021 изнутри.
Redocly (генератор Swagger-API-доки) рассказали как прошло их участие в Google Season of Docs.
Если вы хотите принять участие как контрибьютор или ваша организация хочет подать своей проект на участие, или же вам просто интересно как устроены такие ивенты изнутри — статья для вас.
Очень приятная открытость изложения, рассказали даже о таких щепетильных моментиках как бюджетирование. Структура статьие четкая и ясная, вот такая была проблема, вот решили делать то-то, а успех планируем замерять вот так.
Можно поглазеть на созданные PRы, ознакомиться с таймлайном, чтобы примерно понять сколько что займет времени и наконец-то задуматься об участии в следующем году!
🔗 Читать: Redocly - Season of Docs 2021: Case study
#en #article
Redocly (генератор Swagger-API-доки) рассказали как прошло их участие в Google Season of Docs.
Если вы хотите принять участие как контрибьютор или ваша организация хочет подать своей проект на участие, или же вам просто интересно как устроены такие ивенты изнутри — статья для вас.
Очень приятная открытость изложения, рассказали даже о таких щепетильных моментиках как бюджетирование. Структура статьие четкая и ясная, вот такая была проблема, вот решили делать то-то, а успех планируем замерять вот так.
Можно поглазеть на созданные PRы, ознакомиться с таймлайном, чтобы примерно понять сколько что займет времени и наконец-то задуматься об участии в следующем году!
🔗 Читать: Redocly - Season of Docs 2021: Case study
#en #article
❤1👍1
Обновилось годное дополнение для Google Docs: Docs to Markdown.
Как можно понять из названия, позволяет в пару взмахов пальцами конвертировать вашу гугл-доку в HTML или Markdown без особой головоморочки.
Обновление минорное, добавили возможность убрать пугающие красные ворнинги, но может кто не знал о плагинчике.
#markdown #tool #en
Как можно понять из названия, позволяет в пару взмахов пальцами конвертировать вашу гугл-доку в HTML или Markdown без особой головоморочки.
Обновление минорное, добавили возможность убрать пугающие красные ворнинги, но может кто не знал о плагинчике.
#markdown #tool #en
👍1
Forwarded from Shut up and write (Shut_up_and_write_bot)
Docs for Developers
Обзор на книгу Docs for Developers: An Engineer’s Field Guide to Technical Writing, которая вышла в сентябре 2021. В посте есть спойлеры, если хотите сохранить интригу не читайте этот пост.
Книга написана в соавторстве техническими писателями из Google, Microsoft, Stripe и Monzo.
Авторы говорят, что:
Что зашло
- Легко и быстро читается.
- Книга построена как хорошая документация, не обязательно читать ее всю, если есть пробелы в какой-то конкретной теме, например, вы не знаете как оценить качество документации, то можно прочитать только одну главу. Хотя авторы рекомендуют читать книгу по порядку 😉
- Из книги можно собрать коллекцию цитат про важность документации и правильные подходы. Тезисы подтверждены ссылками на научные статьи. Я нашла статьи, которые раньше не читала.
- Есть список необходимых инструментов, чтобы написать и опубликовать первую документацию (Hugo, Vale, Netlify).
Не зашло
- Я не люблю рассказы внутри обучающих книг, а тут был рассказ про стартап, который не документировал свой API, а потом им нужно было обучить первого клиента и они ой как пожалели. Пример мне показался слишком далеким от реальности. Я эти части пропускала, чем закончилась история не знаю.
- Я ожидала прочитать реальные истории из опыта авторов, про подходы к документации в их компаниях и много практики. Этого в книге нет.
Однако
Книга мне понравилась. Но перечитывать и держать ее под рукой я не буду.
Книга подойдет всем начинающим техническим писателям. Потому что в ней не только про документацию для разработчиков. В книге есть много базовых вещей: что нужно определить аудиторию вашей документации и писать для нее; что документацию сканируют, а не читают; что писать нужно коротко, текст делить на блоки. Эти принципы правдивы для любой документации.
Если вы технический писатель с опытом, то бросать все и начинать читать книгу не надо.
Я не верю, что много разработчиков или менеджеров прочитает ее, особенно кто-то из стартапа, ведь это 200 страниц.
#developerexperience
Обзор на книгу Docs for Developers: An Engineer’s Field Guide to Technical Writing, которая вышла в сентябре 2021. В посте есть спойлеры, если хотите сохранить интригу не читайте этот пост.
Книга написана в соавторстве техническими писателями из Google, Microsoft, Stripe и Monzo.
Авторы говорят, что:
Книга разработана как ресурс, который нужно держать под рукой, чтобы вы могли включить написание документацию в процесс разработки. Эта книга поможет вам создать документацию с нуля. ©Еще обсуждение книги с авторами можно послушать в подкасте Write the Docs.
Что зашло
- Легко и быстро читается.
- Книга построена как хорошая документация, не обязательно читать ее всю, если есть пробелы в какой-то конкретной теме, например, вы не знаете как оценить качество документации, то можно прочитать только одну главу. Хотя авторы рекомендуют читать книгу по порядку 😉
- Из книги можно собрать коллекцию цитат про важность документации и правильные подходы. Тезисы подтверждены ссылками на научные статьи. Я нашла статьи, которые раньше не читала.
- Есть список необходимых инструментов, чтобы написать и опубликовать первую документацию (Hugo, Vale, Netlify).
Не зашло
- Я не люблю рассказы внутри обучающих книг, а тут был рассказ про стартап, который не документировал свой API, а потом им нужно было обучить первого клиента и они ой как пожалели. Пример мне показался слишком далеким от реальности. Я эти части пропускала, чем закончилась история не знаю.
- Я ожидала прочитать реальные истории из опыта авторов, про подходы к документации в их компаниях и много практики. Этого в книге нет.
Однако
Книга мне понравилась. Но перечитывать и держать ее под рукой я не буду.
Книга подойдет всем начинающим техническим писателям. Потому что в ней не только про документацию для разработчиков. В книге есть много базовых вещей: что нужно определить аудиторию вашей документации и писать для нее; что документацию сканируют, а не читают; что писать нужно коротко, текст делить на блоки. Эти принципы правдивы для любой документации.
Если вы технический писатель с опытом, то бросать все и начинать читать книгу не надо.
Я не верю, что много разработчиков или менеджеров прочитает ее, особенно кто-то из стартапа, ведь это 200 страниц.
#developerexperience
Docs for Developers
Documentation for Everyone
👍4
Информативный пост написанный по мотивам Knowledge Conf-доклада Семёна Факторовича, руководителя documentat.io о чувстве «бесполезности» документации (и не только).
>Чаще всего за словом «бесполезна» кроется ощущение, что документация не очень хорошо выполняет свою задачу. Потому что она либо не полна, то есть описывает не все аспекты, которые хотелось бы в ней найти. Либо не точна, то есть то, что в ней написано, не полностью соответствует истине. Либо не актуальна, то есть соответствовала истине в прошлом, а сейчас программная система или внешний мир изменились, и документация перестала этому соответствовать.
Эти проблемы и обсуждаются в этой статье. Семен предлагает взглянуть на вышеуказанные симптомы, как их интерпретировать, а самое главное — что с ними делать.
❗️Наша редакция уважает Семёна и рекомендует статью к прочтению.
🔗 Читать: Вам кажется, что с вашей документацией что-то не так? Вам не кажется
#article #ru
>Чаще всего за словом «бесполезна» кроется ощущение, что документация не очень хорошо выполняет свою задачу. Потому что она либо не полна, то есть описывает не все аспекты, которые хотелось бы в ней найти. Либо не точна, то есть то, что в ней написано, не полностью соответствует истине. Либо не актуальна, то есть соответствовала истине в прошлом, а сейчас программная система или внешний мир изменились, и документация перестала этому соответствовать.
Эти проблемы и обсуждаются в этой статье. Семен предлагает взглянуть на вышеуказанные симптомы, как их интерпретировать, а самое главное — что с ними делать.
❗️Наша редакция уважает Семёна и рекомендует статью к прочтению.
🔗 Читать: Вам кажется, что с вашей документацией что-то не так? Вам не кажется
#article #ru
Хабр
Вам кажется, что с вашей документацией что-то не так? Вам не кажется
Меня зовут Семён Факторович, с 2012 года я занимаюсь технической документацией. Последние три года я руковожу собственным агентством documentat.io , помогая российским IT-компаниям создавать...
❤1👍1🤯1
Заметки о Release Notes
Релиз ноуты — неотъемлемая часть любого (опенсорсного, а по факту любого осознанного) проекта. Релиз ноуты не просто должны быть, но должны быть читабельными и полезными одновременно.
В этой статье автор предлагает 10 разумных пунктов по улучшению ваших релиз ноутов, показывает примеры и делится некоторыми рассуждениями на счет релиз ноутов с примечаниями.
🔗 Читать: Writing better release notes
P.S
Мы уже не раз писали о релиз ноутах, дóроги они сердцу нашей редакции, так что предлагаю оглянуться назад:
1. The art of writing great release notes
2. Masters of Product Change: Taylor Singletary - Slack
3. Medium Release Notes: Historical record of the oft-overlooked communique known as the release note & Discord Changelogs
#changelog #en #article #resource
Релиз ноуты — неотъемлемая часть любого (опенсорсного, а по факту любого осознанного) проекта. Релиз ноуты не просто должны быть, но должны быть читабельными и полезными одновременно.
В этой статье автор предлагает 10 разумных пунктов по улучшению ваших релиз ноутов, показывает примеры и делится некоторыми рассуждениями на счет релиз ноутов с примечаниями.
🔗 Читать: Writing better release notes
P.S
Мы уже не раз писали о релиз ноутах, дóроги они сердцу нашей редакции, так что предлагаю оглянуться назад:
1. The art of writing great release notes
2. Masters of Product Change: Taylor Singletary - Slack
3. Medium Release Notes: Historical record of the oft-overlooked communique known as the release note & Discord Changelogs
#changelog #en #article #resource
❤6👍2
Вспомнилось тут в свете (надеюсь) скорого релиза IDE от JetBrains для техписателей, что есть кайфовый плагин для IntelliJ IDEA которым можно пользоваться уже сейчас.
Проверяет орфографию, грамматику и стиль, такой себе встроенный граммарли
🔗 Почитать больше о Grazie
#testthedocs #ide #en
Проверяет орфографию, грамматику и стиль, такой себе встроенный граммарли
🔗 Почитать больше о Grazie
#testthedocs #ide #en
👍9❤3
Свершилось! Теперь не только GitLab умеет в Mermaid-диаграммы, а и сам GitHub наконец-то созрел и заимплементил пожалуй самую удобную тулу для рисования понятных и красивых диаграмок.
🔗 Читать: Include diagrams in your Markdown files with Mermaid
#diagram #tool #en
🔗 Читать: Include diagrams in your Markdown files with Mermaid
#diagram #tool #en
❤7👍6
Наткнулся на приятную заметку о любви к старым бумажным мануалам к, собственно, старому софту и железу. Я сам питаю неаргументированную любовь к старым инструкциям (и инструкциям к древним военным штуковинам), что-то в них такое есть. Эта статья поняла чётче осознать чем они так манят и почему они читаются и выглядят намного приятнее, чем практически любая современная инструкция.
Рекомендую, короткое спокойное чтиво на 5-6 минут, но сколько же души в этом всём. Может и вы откроете в себе любовь к “ископаемым”.
🔗 Читать: Why I collect and read old computer manuals
#visual #vintage #example #en
Рекомендую, короткое спокойное чтиво на 5-6 минут, но сколько же души в этом всём. Может и вы откроете в себе любовь к “ископаемым”.
🔗 Читать: Why I collect and read old computer manuals
#visual #vintage #example #en
👍8❤4
В это пиздецовое непростое время многим моим согражданам Украинцам пришлось уехать из своих домов, покинуть свой город и даже страну. Некоторые заграничные заказчики ссыкливо отказываются от сотрудников Украине, бизнесы замораживаются или прекращают существовать. Многие потеряли не только дом, но и работу.
Мне время от времени поступают различные предложения от контор, которые готовы поддерживать и принимать Украинцев или помогать с релокейтом, буду ими с вами делиться по мере поступления. 🇺🇦 💪
Во-первых, для всего этого есть отдельный сервис: UA Talents
Во-вторых: Вакансия —> Компания: Klarna. Локация: Берлин, Германия. Предлагают релокейшн-саппорт.
В-третьих: Вакансия —> Компания: Star. Локация: Wroclaw, Poland; Remote, EU Time Zone, Клиент из UK
UPD:
ДОБІРКА САЙТІВ З ПОШУКУ РОБОТИ:
✅ https://helpukrainians.jooble.org
✅ https://www.jobaidukraine.com
✅ https://hireforukraine.org
✅ https://www.jobs4ukraine.eu
✅ https://remoteukraine.org
✅ https://hrforukraine.notion.site
Подолаємо труднощі разом та переможемо 🇺🇦
#career #vacancy
Мне время от времени поступают различные предложения от контор, которые готовы поддерживать и принимать Украинцев или помогать с релокейтом, буду ими с вами делиться по мере поступления. 🇺🇦 💪
Во-первых, для всего этого есть отдельный сервис: UA Talents
Во-вторых: Вакансия —> Компания: Klarna. Локация: Берлин, Германия. Предлагают релокейшн-саппорт.
В-третьих: Вакансия —> Компания: Star. Локация: Wroclaw, Poland; Remote, EU Time Zone, Клиент из UK
UPD:
ДОБІРКА САЙТІВ З ПОШУКУ РОБОТИ:
✅ https://helpukrainians.jooble.org
✅ https://www.jobaidukraine.com
✅ https://hireforukraine.org
✅ https://www.jobs4ukraine.eu
✅ https://remoteukraine.org
✅ https://hrforukraine.notion.site
Подолаємо труднощі разом та переможемо 🇺🇦
#career #vacancy
👍38❤5👎1
Доброго вечора, IT-спільнота, ми з України! Ситуація наступна: світу зараз як ніколи потрібні ви — вільні, працездатні, у безпеці.
До війни ми почали об'єднувати найдивовижніших, інноваційних людей України з метою створення неймовірних інноваційних продуктів. Тепер ми виходимо на новий рівень.
Ми хочемо надати вам роботу, офіс та житло. Ми хочемо знайти якнайбільше людей, які вірять, що майбутнє в їхніх руках.
Давайте зробимо світ кращим! 👇
https://bit.ly/3qlBc8I
#career #vacancy
До війни ми почали об'єднувати найдивовижніших, інноваційних людей України з метою створення неймовірних інноваційних продуктів. Тепер ми виходимо на новий рівень.
Ми хочемо надати вам роботу, офіс та житло. Ми хочемо знайти якнайбільше людей, які вірять, що майбутнє в їхніх руках.
Давайте зробимо світ кращим! 👇
https://bit.ly/3qlBc8I
#career #vacancy
❤24👍9💩1
Всем здрасьте! 🇺🇦
Наши ряды слегонца самоочистились от поехавших, так что можно снова дышать полной грудью.
🗣 Ну а теперь к новостям:
1. У канала случился незначительный но крайне приятный фейс-лифт. Канал естественно продолжит радовать вас свежайшим и актуальнейшим контентом по всем темам связанным с написанием документации, но теперь делать это будет гораздо удобнее.
Я мощнейше запотел, но все же оформил какую-никакую навигацию по каналу, протегал по темам и языкам все вышедшие посты. В будущем буду обновлять пост с навигацией (предлагайте дополнительные хэштеги в комментариях!) . Он будет следующим после этого и всегда жить в шапке канала.
2. Кроме навигации, улучшайзингу подверглась и айдентика 🧑🎨 Теперь посты будут сопровождаться красивой meaningful карточкой с кратким синопсисом поста, пример - в этом же посте.
Логотип также претерпел небольших изменений, теперь мы используем модный хипстерский шрифт с лигатурами и вот этим вот всем (им же я пользуюсь при написании документации в IDE, чего и вам советую, шрифт - Fira Code).
Наши ряды слегонца самоочистились от поехавших, так что можно снова дышать полной грудью.
🗣 Ну а теперь к новостям:
1. У канала случился незначительный но крайне приятный фейс-лифт. Канал естественно продолжит радовать вас свежайшим и актуальнейшим контентом по всем темам связанным с написанием документации, но теперь делать это будет гораздо удобнее.
Я мощнейше запотел, но все же оформил какую-никакую навигацию по каналу, протегал по темам и языкам все вышедшие посты. В будущем буду обновлять пост с навигацией (предлагайте дополнительные хэштеги в комментариях!) . Он будет следующим после этого и всегда жить в шапке канала.
2. Кроме навигации, улучшайзингу подверглась и айдентика 🧑🎨 Теперь посты будут сопровождаться красивой meaningful карточкой с кратким синопсисом поста, пример - в этом же посте.
Логотип также претерпел небольших изменений, теперь мы используем модный хипстерский шрифт с лигатурами и вот этим вот всем (им же я пользуюсь при написании документации в IDE, чего и вам советую, шрифт - Fira Code).
👍27❤20🤡1
👅 Языки:
#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 — что-то совсем косвенно относящееся к техписательству, юморески
Предлагайте новые хэштеги в комментариях!
👍51❤18🤡2
Stripe заопенсорсили Markdoc. Markdoc — это authoring система на основе Markdown, на которой работает веб-сайт документации Stripe который мы все любим и ставим в пример каждый раз когда кто-то спрашивает примеры хорошей документации.
Markdoc подходит как для обычных статических сайтиков, так и для фичастых сайтов с документацией или личных блогов.
Stripe подготовили довольно неплохую документацию, интерактивный плейграунд и несколько статеек о начале работы с Markdoc и даже о создании простого плагина.
#tool #en #markdown #SSG
Markdoc подходит как для обычных статических сайтиков, так и для фичастых сайтов с документацией или личных блогов.
Stripe подготовили довольно неплохую документацию, интерактивный плейграунд и несколько статеек о начале работы с Markdoc и даже о создании простого плагина.
#tool #en #markdown #SSG
❤26❤🔥9👍1
У 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
👍29❤7
shot-scraper — CLI тулза для для автоматического создания скриншотов веб-сайтов.
shot-scraper помогает автоматизировать создание свежих скринов веб-приложений (можно скринить конкретную часть приложения/сайта) для последующей интеграции в документацию, чтобы визуал не отставал от контента. Можно засунуть в CI\CD и всякое такое.
Бонусом у утилиты отличная документация и два [1]блог [2]поста которые рассказывют как всем этим пользоваться, и зачем, и как это создавалось.
#en #tool #visual #screenshot
Technical Writing 101
shot-scraper помогает автоматизировать создание свежих скринов веб-приложений (можно скринить конкретную часть приложения/сайта) для последующей интеграции в документацию, чтобы визуал не отставал от контента. Можно засунуть в CI\CD и всякое такое.
Бонусом у утилиты отличная документация и два [1]блог [2]поста которые рассказывют как всем этим пользоваться, и зачем, и как это создавалось.
#en #tool #visual #screenshot
Technical Writing 101
👍23🤯3
После 4 лет работы, 75 альфа-версий и 22 бета-версий следующfя мажорная версия Docusaurus готова к продакшену.
Из главных новшеств:
- Поддержка MDX: позволяет интегрировать интерактивные React компоненты прямо в документации. Пример
- Плагины: Docusaurus теперь имеет модульную архитектуру с системой плагинов. Основные функции, такие как документация, блог, страницы и поиск, работают как отдельные плагины. Доступны дополнительные плагины, например docusaurus-search-local, как замена Algolia. Больше плагинов тут
- Поддержка PWA
- Удобное версионирование документации
С более мелкими улучшениями можно ознакомиться в официальном блог посте
Читать: Announcing Docusaurus 2.0
#en #SSG #tool #markdown
Technical Writing 101
Из главных новшеств:
- Поддержка MDX: позволяет интегрировать интерактивные React компоненты прямо в документации. Пример
- Плагины: Docusaurus теперь имеет модульную архитектуру с системой плагинов. Основные функции, такие как документация, блог, страницы и поиск, работают как отдельные плагины. Доступны дополнительные плагины, например docusaurus-search-local, как замена Algolia. Больше плагинов тут
- Поддержка PWA
- Удобное версионирование документации
С более мелкими улучшениями можно ознакомиться в официальном блог посте
Читать: Announcing Docusaurus 2.0
#en #SSG #tool #markdown
Technical Writing 101
❤14❤🔥2👍1