Получи случайную криптовалюту за регистрацию!

Shut up and write

Логотип телеграм канала @shut_up_and_write — Shut up and write S
Логотип телеграм канала @shut_up_and_write — Shut up and write
Адрес канала: @shut_up_and_write
Категории: Технологии
Язык: Русский
Страна: Россия
Количество подписчиков: 731
Описание канала:

Я Маша и я технический писатель. Очень люблю документацию, особенно хорошую. Читаю все подряд: инструкции к стиральным машинам, правила пользования метро и справки разных сервисов.
На канале пишу о том, что понравилось или не понравилось.
@the_real_mari

Рейтинги и Отзывы

1.67

3 отзыва

Оценить канал shut_up_and_write и оставить отзыв — могут только зарегестрированные пользователи. Все отзывы проходят модерацию.

5 звезд

0

4 звезд

0

3 звезд

0

2 звезд

2

1 звезд

1


Последние сообщения

2022-02-04 15:00:31 Как Twilio создают документацию

Пересказ доклада Twilio про пределывание их документации. Полностью доклад можно посмотреть в одном из видео (раз и два, содержание на 80% совпадает) или почитать у них в блоге.

Предыстория

Когда-то давно документация Twilio содержала много текста, который объяснял сложные концепции их сервиса, как все устроено. Это была хорошо организованная документация. Тогда это было 1000 страниц, которые поддерживали 5 инженеров. Все было хорошо, но почему бы не сделать лучше.

Twilio провели исследования, отзывы на документацию были хорошие, разработчикам все нравилось. Но когда разработчиков попросили показать, как они пользуются документацией, то оказалось разработчики пролистывали документацию к коду, читали пример кода, если он им подходил, то брали его, если нет, то искали дальше. После нескольких неуспешных попыток они шли в гугл и в итоге находили нужную страницу документации. Разработчики не использовали оглавление и хорошо структурированное меню для поиска информации.

Поэтому Twilio стали придумывать code-first документационные решения, которые будут рассказывать разработчикам как пользоваться их сервисом через код.

Инструменты

Для сайта документации они использовали:
- Wagtail CMS на базе Django. С помощью инструмента StreamField можно комбинировать структурированные и неструктурированный контент. Twilio используют этот инструмент для вставки примеров кода в документацию.
- Github, где хранят все примеры кода в отдельном репозитории и тестируют их как настоящий код. А еще получают PR от внешних разработчиков, которые попробовали пример кода и знают, как его можно улучшить.

Для аналитики и исследований:
- Optimizely для а/б тестирования.
- MixPanel и Google Analytics для метрик.
- UserTesting для видео интервью с разработчиками.

Еще несколько открытий Twilio про поведение разработчиков

- главное помочь разработчику пройти первый шаг: разработчик скорее доделает гайд до конца, если у него получился первый шаг.
- чем меньше текста перед примером кода, тем лучше: у страниц, где было 4 предложения перед примером кода, показатели в 2 раза лучше тех, где перед примером кода 11 строк.

#developerexperience
1.1K viewsShut_up_and_write_bot, 12:00
Открыть/Комментировать
2022-01-21 15:00:56 Docs for Developers

Обзор на книгу 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
2.4K viewsShut_up_and_write_bot, 12:00
Открыть/Комментировать
2022-01-14 15:00:06 Про редизайн документации GitLab - 2

GitLab проводит ежегодные опросы пользователей, чтобы оценить качество своей документации. Результаты опроса этого года они опубликовали на Youtube. Про опрос прошлого года писала тут.

Между опросами GitLab переделали левое меню навигации и сделали редизайн документации. Эти изменения должны помочь пользователям находить нужные страницы и информацию на них.
Задачи можно найти на роадмапе документации.

Результаты нового опроса

В сентябре 2021 GitLab снова опросили пользователей, чтобы понять, что изменилось. Опрос показал, что:

- пользователям стало сложнее находить информацию (67% нашли то, что искали, в прошлом году было 75%)
- сложнее всего найти информацию по решению проблем, результаты совпадают с прошлым годом
- пользователи все еще считают найденный контент полезным
- выросло число новых пользователей GitLab, которые посещают документацию

Почему пользователям стало сложнее находить информацию

Такое изменение находимости контента могло произойти потому что:

- появилось много новых пользователей
- процесс изменения структуры документации не закончен
- появилось много нового контента без улучшения поиска

#экспериментыналюдях
649 viewsShut_up_and_write_bot, 12:00
Открыть/Комментировать
2022-01-07 15:00:14 2021 → 2022

Краткое содержание 2021 и тренды на 2022.

Что произошло за 2021 год

- Gitlab, Canonical, Airbnb, Github, SAP
писали про переработку своих сайтов документации и про то, как это важно.

- согласно опросам SmartBear, Postman, Github, Google документация важна и нужна.

- JetBrains разрабатывают IDE для технических писателей.

- зарплаты технических писателей изменились не сильно судя по опросам за 2020 и 2019 года, но результаты 2021 года пока не опубликованы.

Тренды на 2022

В Cherryleaf собрали предсказания от технических писателей. Чаще всего там повторяются: UX-писательство, Dev experience (API документация и портал разработчика) и видеодокументация.

Очень много разным мнений, мне близки эти:

- от Stoplight: автоматизация создания документации, переиспользование контента и интерактивная документация. У них еще есть статья про тренды в API 2022.

- от вице-президента Meta по дизайну контента. Метавселенная поменят опыт людей и их взаимодействие с интерфейсом. Одной из новых задач для дизайнеров контента будет объяснений пользователяем, как ориентироваться в новом метапространстве (AR и VR). Но точного понимания, как повлияет появление метавселенной на дизайнеров контента, пока нет.
1.0K viewsShut_up_and_write_bot, 12:00
Открыть/Комментировать
2021-12-24 15:00:21 ​​Какой длины делать обучающие видео?

Компания TechSmith, которая делает Snagit и Camtasia, опубликовала исследование про видео контент. С помощью исследования они пытались понять, почему люди начинают, останавливаются и продолжают смотреть обучающие и информационные видеоролики.

- Исследование Video Viewer Study 2021
- Статья Video Length: How Long Should Instructional Videos Be?
- Статья Video Statistics, Habits, and Trends You Need To Know

Как проходило исследование

В ходе исследования ​​914 человек 20 разных профессий из 6 стран отвечали на вопросы и описывали “отличное” видео, которые они посмотрели недавно и оно помогло им в работе.

Какие выводы

- 83% респондентов предпочитают видеоформат для учебного или информационного контента.

- 71% респондентов смотрят два или более обучающих видео в неделю (на 33% больше, чем в 2018 году).

- Идеальной длины видео не существует, респонденты выбирали разные варианты в диапазоне 3-19 минут, при этом если цель респондента получить новые знания или ему интересна эта область, то он готов смотреть ролики 20-40 минут, если нужно решить проблему — то ролик до 9 минут, а короткие ролики в 1-2 минуты выбрали те, чья мотивация звучала как “Я должен был это посмотреть”.

- Видео выбирают по описанию и названию, а смотрят на Youtube.

- Видео продолжают смотреть, если материал хорошо организован, и перестают смотреть, когда получили нужную информацию или не получили информацию, которую ожидали. Качество видео и видеоэффекты не так важны.

#экспериментыналюдях #самсебережиссер
696 viewsShut_up_and_write_bot, 12:00
Открыть/Комментировать
2021-12-17 15:00:47 The Best Developer Portals of 2021

Объявили победителей премии The Best Developer Portals. Всего было номинировано 49 порталов. Про процесс оценки порталов жюри рассказали в интервью.

Кто победил

Лучший портал выбирали среди тех порталов, которые уже получили награду в других категориях. В итоге победили:

- Ably Developer Platform – лучший девпортал для малого и среднего бизнеса.
Жюри оценили простоту и удобство сайта, хороший баланс между визуальными эффектами и деталями, а также ориентированность сайта на разработчиков. В прошлом году Ably заняли второе место. Еще они выиграли Best API Business Model и Best Use of API Gateway Integration.

- FusionCreator Developer Portal – лучший девпортал для крупных компаний.
Тут жюри отметили подробную справочную документацию, хороший раздел начало работы, множество видео контента, и три различных типа навигации в документации. Еще они выиграли Best Findability of Products.

Победители в других номинациях

- BT API Developer Portal – лучший внутренний девпортал, потому что содержит все, что ожидается от отличного портала разработчиков, например, примеры кода и песочницу, а также множество полезной информации для внутренних разработчиков. Для внутренних разработчиков предусмотрен упрощенный процесс доступа к API. Демо портала.

- platformOS – лучший онбординг и лучший процесс редактирования, жюри отметили процесс публикации, который включает автоматизированное тестирование документации, и весь рабочий процесс, который следует принципам docs-as-code. Демо портала.

- Plaid's Developer Portal and Documentation – лучшая API Reference документация и лучший дизайн, потому что сайт хорошо структурирован и хорошо использует пустое пространство, а контент легко быстро понять благодаря множеству примеров кода.

- Algolia – лучшая монетизация, потому что прозрачно рассказывают про ценообразования и дают рекомендации, которые помогут разработчикам выбрать подходящую конфигурацию.

- Xsolla – лучшая локализация девпортала, поддерживают 6 языков. Доклад Xsolla про локализацию на Apidays LIVE Paris.

- BNI API Digital Services – приз зрительских симпатий.

Полный список победителей.

#developerexperience
265 viewsShut_up_and_write_bot, 12:00
Открыть/Комментировать
2021-12-03 15:00:11 Краткое содержание. Ноябрь

- Canonical (делают Ubuntu) опубликовали свои планы по преобразованию документации. За основу документации берут фреймворк Diátaxis. Считают, что документация очень важна. Планируют создать и поддерживать техническую документацию и практику документирования, которые будут представлять собой стандарт в отрасли.

- Github опубликовали ежегодный отчет. Документация часто является недостаточно обеспеченной областью проектов, несмотря на то, что она имеет решающее значение для привлечения новых участников, повышения качества работы и создания общего понимания. Разработчики видят примерно 50% повышение производительности благодаря простой в использовании документации.

- Postman опубликовали 2021 State of the API Report. Документация один из топ 4-х факторов, которые учитываются при интеграции с API. Главным препятствии для использования API назвали отсутствие документации, так ответили 55 % респондентов. Наиболее полезным улучшением в документации API – это улучшенные примеры, примеры кода и стандартизация.

- Confluence добавили возможность вставить несколько Excerpt macros с одной и той же страницы.

- DITA контент теперь можно публиковать с помощью mkdocs.

- А в Ditto (инструмент для работы с текстами в интерфейсе) можно добавлять переменные в текст.

- Redocly рассказали про преимущества их VS Code extension.

Планы на декабрь

- Вторая часть вручения DevPortal Awards. Бесплатно, онлайн.

- Митап Tempo presents: Scaling your content team. Платно, онлайн.

- Митап Delightful Editorial Experiences. A Sanity.io Open House. Бесплатно, онлайн.

- Адвент календарь про лучшие практики Confluence от k15t.

#полезныессылки
290 viewsShut_up_and_write_bot, 12:00
Открыть/Комментировать
2021-11-26 15:00:47 Эмоций разработчиков по отношению к документации

Группа ученых из университета Indian Institute of Technology Tirupati провела эмоциональный анализ комментариев в коммитах, связанных с документацией.

- Understanding Emotions of Developer Community Towards Software Documentation, 2021 год
- Видео версия

Как проходило исследование

Ученые взяли 10 000 комментариев из коммитов, которые относятся к файлам README или файлам с расширением .txt или .md. Проанализировали слова, которые используют разработчики, и связали эти слова с эмоциями. Чтобы распознать эмоции использовали методологию NRC Word-Emotion Association Lexicon. Она позволяет определить 8 эмоций: гнев, ожидание, отвращение, страх, радость, печаль, удивление, доверие. Если какой-то комментарий выражал несколько эмоций, то выбирали более сильную.

Примеры того, какие комментарии соответствуют каким эмоциям, жирным выделены слова, которые характеризуют эмоцию:

- Improve duplicate torrent detection — доверие
- README is better short-n-sweet — радость
- Improved test framework, added missing dependencies — страх
- Make usage instructions more clear — ожидание
- drop support for older versions — печаль
- Location support (backward compatibility broken) — гнев
- plugin-browser-for-bbpress: A stupid bug. Tagged version 0.1.9 — отвращение
- Didn’t expect this to actually become a thing — удивление

Какие выводы

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

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

То, что доверие — самая частая эмоция, может означать, что:
- большинство разработчиков доверяют существующей документации
- обновления документации считается разработчиками правильным действием
Высокое доверие может быть причиной того, что разработчики вносят лишь незначительные изменения в существующую документацию.

P.S. Я не считаю, что исследование дает полную картину, так как в нем учтены только те, кто внес изменения в документацию. Но мне было интересно узнать их эмоции и понравился подход.

#экспериментыналюдях
540 viewsShut_up_and_write_bot, 12:00
Открыть/Комментировать
2021-11-19 15:00:26 API Explorers or Try it

Продолжу про API Explorer. Вот у каких компаний мне удалось его найти:

- Facebook API Explorer. Доступен только после регистрации. Без регистрации можно посмотреть инструкцию к нему.

- Asana API Explorer. И них у тоже есть инструкция к нему.

- Google API Explorer и инструкция.

- Adyen API Explorer. Они планируют выложить его в открытый доступ, но пока еще нет.

- DocuSign API Explorer и API Request Builder. Писала про них выше.

Как можно сделать самим

Вам понадобится Open API спецификация, потому что все инструменты, которые я знаю, за основу берут ее.

Потом можно взять готовое и платное решение:
- APIMATIC
- Redocly
- Apiary

Или воспользоваться чем-то бесплатными и доработать:
- Swagger UI или он же, но в более современном дизайне
- RapiDoc
- Readme
- Rhosys
- DapperDox
- Adyen API Explorer, но тут нужно подождать, пока его выложат в open source

#developerexperience #тулзы
370 viewsShut_up_and_write_bot, edited  12:00
Открыть/Комментировать
2021-11-12 15:00:32 API Explorer DocuSign

API Explorer и API Request Builder — это части портала разработчика DocuSign.

С их помощью можно:
- протестировать API пока читаете документацию, не написав ни строчки кода
- убедиться, что в документации все верно и ты все правильно понял
- написать первый прототип быстрее, потому что уже есть код, который можно использовать

За этот год DocuSign запустили новую версию API Explorer, потом доработали ее, а потом создали API Request Builder.
Я не смогла найти информацию о том, какие инструменты DocuSign используют, а жаль.

Еще из интересного в их портале разработчика есть:
- быстрый старт, каждый шаг в котором доступен только после прохождения предыдущего
- форум, на котором можно предложить доработку в API или проголосовать за что-то из уже предложенного, например, за темную тему в документации
- обучающие тренинги для разработчиков

#makedocumentationgreat #developerexperience
551 viewsShut_up_and_write_bot, 12:00
Открыть/Комментировать