4 Feb 2022, 12:00 UTC≈4,930 views23 reactionsread 8 August 2026 Как Twilio создают документацию
Пересказ доклада Twilio про пределывание их документации. Полностью доклад можно посмотреть в одном из видео (раз и два, содержание на 80% совпадает) или почитать у них в блоге.
Предыстория
Когда-то давно документация Twilio содержала много текста, который объяснял сложные концепции их сервиса, как все устроено. Это была хорошо организованная документация. Тогда это было 1000 страни…
👍15🔥4❤3😁1
Signed Shut_up_and_write_bot
21 Jan 2022, 12:00 UTC≈5,490 views12 reactionsread 8 August 2026 Docs for Developers
Обзор на книгу Docs for Developers: An Engineer’s Field Guide to Technical Writing, которая вышла в сентябре 2021. В посте есть спойлеры, если хотите сохранить интригу не читайте этот пост.
Книга написана в соавторстве техническими писателями из Google, Microsoft, Stripe и Monzo.
Авторы говорят, что:
Книга разработана как ресурс, который нужно держать под рукой, чтобы вы могли включить написан…
👍12
Signed Shut_up_and_write_bot
14 Jan 2022, 12:00 UTC≈1,850 views1 reactionsread 8 August 2026 Про редизайн документации GitLab - 2
GitLab проводит ежегодные опросы пользователей, чтобы оценить качество своей документации. Результаты опроса этого года они опубликовали на Youtube. Про опрос прошлого года писала тут.
Между опросами GitLab переделали левое меню навигации и сделали редизайн документации. Эти изменения должны помочь пользователям находить нужные страницы и информацию на них.
Задачи можно найти на…
👍1
Signed Shut_up_and_write_bot
7 Jan 2022, 12:00 UTC≈1,900 views1 reactionsread 8 August 2026 2021 → 2022
Краткое содержание 2021 и тренды на 2022.
Что произошло за 2021 год
- Gitlab, Canonical, Airbnb, Github, SAP
писали про переработку своих сайтов документации и про то, как это важно.
- согласно опросам SmartBear, Postman, Github, Google документация важна и нужна.
- JetBrains разрабатывают IDE для технических писателей.
- зарплаты технических писателей изменились не сильно судя по опросам за 2020 и…
👍1
Signed Shut_up_and_write_bot
24 Dec 2021, 12:00 UTC≈1,320 viewsread 8 August 2026 Какой длины делать обучающие видео?
Компания TechSmith, которая делает Snagit и Camtasia, опубликовала исследование про видео контент. С помощью исследования они пытались понять, почему люди начинают, останавливаются и продолжают смотреть обучающие и информационные видеоролики.
- Исследование Video Viewer Study 2021
- Статья Video Length: How Long Should Instructional Videos Be?
- Статья Video Statistics, Habits,…
Signed Shut_up_and_write_bot
17 Dec 2021, 12:00 UTC≈1,320 viewsread 8 August 2026 The Best Developer Portals of 2021
Объявили победителей премии The Best Developer Portals. Всего было номинировано 49 порталов. Про процесс оценки порталов жюри рассказали в интервью.
Кто победил
Лучший портал выбирали среди тех порталов, которые уже получили награду в других категориях. В итоге победили:
- Ably Developer Platform – лучший девпортал для малого и среднего бизнеса.
Жюри оценили простоту и удобство …
Signed Shut_up_and_write_bot
3 Dec 2021, 12:00 UTC883 views1 reactionsread 8 August 2026 Краткое содержание. Ноябрь
- Canonical (делают Ubuntu) опубликовали свои планы по преобразованию документации. За основу документации берут фреймворк Diátaxis. Считают, что документация очень важна. Планируют создать и поддерживать техническую документацию и практику документирования, которые будут представлять собой стандарт в отрасли.
- Github опубликовали ежегодный отчет. Документация часто является недостаточно…
👍1
Signed Shut_up_and_write_bot
26 Nov 2021, 12:00 UTC≈1,070 views1 reactionsread 8 August 2026 Эмоций разработчиков по отношению к документации
Группа ученых из университета Indian Institute of Technology Tirupati провела эмоциональный анализ комментариев в коммитах, связанных с документацией.
- Understanding Emotions of Developer Community Towards Software Documentation, 2021 год
- Видео версия
Как проходило исследование
Ученые взяли 10 000 комментариев из коммитов, которые относятся к файлам README или ф…
👍1
Signed Shut_up_and_write_bot
19 Nov 2021, 12:00 UTC852 viewsread 8 August 2026 API Explorers or Try it
Продолжу про API Explorer. Вот у каких компаний мне удалось его найти:
- Facebook API Explorer. Доступен только после регистрации. Без регистрации можно посмотреть инструкцию к нему.
- Asana API Explorer. И них у тоже есть инструкция к нему.
- Google API Explorer и инструкция.
- Adyen API Explorer. Они планируют выложить его в открытый доступ, но пока еще нет.
- DocuSign API Explorer и A…
Signed Shut_up_and_write_bot
12 Nov 2021, 12:00 UTC≈1,010 viewsread 8 August 2026 API Explorer DocuSign
API Explorer и API Request Builder — это части портала разработчика DocuSign.
С их помощью можно:
- протестировать API пока читаете документацию, не написав ни строчки кода
- убедиться, что в документации все верно и ты все правильно понял
- написать первый прототип быстрее, потому что уже есть код, который можно использовать
За этот год DocuSign запустили новую версию API Explorer, потом дор…
Signed Shut_up_and_write_bot
5 Nov 2021, 11:00 UTC≈1,030 viewsread 8 August 2026 Краткое содержание. Октябрь
- Oпрос по зарплатам Write the Docs 2021. Принять участие можно до 20 декабря, результаты опубликуют в феврале 2022.
- Голосование DevPortal Awards 2021. Проголосовать можно до 7 ноября.
- Саммари API Specifications Conference 2021. В будущую спецификацию OpenAPI планируют включить Documentation driven development.
- Статья Chief Information Architect. Когда интернет только появился, л…
Signed Shut_up_and_write_bot
29 Oct 2021, 11:00 UTC≈1,060 views1 reactionsread 8 August 2026 The F-word
Есть распространенный способ собирать фидбек у читателей — добавить в документацию вопрос “Помогла ли вам эта статья” или “Была ли полезна статья”. Задавая такой вопрос, сложно получить фидбек, который можно использовать, потому что информации не хватает.
В исследовании What Documentation Quality Means to Readers, кроме метрик “хорошести” документации, есть формула идеального фидбека. Фидбек должен бы…
👍1
Signed Shut_up_and_write_bot
Showing the 12 most recent of 20 posts we hold for @shut_up_and_write. View and reaction counts are the latest single reading for each post, not a live figure, and a recent post is still accumulating both. A view count marked ≈ was rounded by Telegram before we ever saw it — t.me prints views in full below 1,000 and to three significant figures above, so ≈1,200,000 means somewhere between 1,150,000 and 1,249,999. Unmarked counts are exact. Text is reproduced from the public post preview and truncated for length.
