Краткое содержание. Август

- В Cloud Native Computing Foundation Community Awards 2021 включили номинацию Top Documentarian.

- Статья про то, должны ли технические писатели получать больше разработчиков.
Документация является неотъемлемой частью продукта, как и код. Поэтому работа технических писателей должна оплачиваться наравне с разработчиками. Согласно опросам, средние базовые зарплаты разработчика и технического писателя в США совпадают. Но это средние базовые зарплаты, у 25 % разработчиков зарплаты выше среднего, нет данных про такие же зарплаты для технических писателей. Статью обсуждали в Twitter и Slack.

- Статья Sarah Maddox про связь проклятия знания, синдрома самозванца и метазнания.
Если мы не понимаем, как много мы знаем и что это может кто-то не знать (проклятие знания), то можем думать, что другие люди знают намного больше нас и мы не заслуживаем достигнутого успеха или похвалы (синдром самозванца). Знание того, что мы знаем, — это метазнание. Прокачать свое метазнание можно через менторство или блог.

- Статья BBC про исследования UX-текстов. Часть 1 и часть 2.
В ней собраны различных тесты для текстов и метрики, на которые стоит обратить внимание, например: понимание текста и восприятие бренда, время, проведенное на странице, % пользователей, которые успешно или нет выполнили какое-то действие.

- Статья про пользу совместной работы технических и UX писателей.
Совместно легче поддерживать единый стиль и консистентность между документацией и интерфейсом, можно вычитывать друг друга, обмениваться хорошими формулировками и знаниями о продукте. А еще технические писатели могут объяснять сложные штуки понятнее, чем разработчики.

- Scott Kubie отвечает, обязательно ли быть носителем языка, чтобы преуспеть в качестве UX-писателя.
У неносителей языка есть преимущества при работе над контентом для международной аудитории или контентом, который необходимо будет перевести на несколько языков. Есть и недостатки, неноситель может допускать ошибки, но такое бывает и с носителями языка.

- Статья про то, что создателям контента не хватает термина для названия специальности.
В отрасли нет единого мнения по поводу названия ролей и отличий между ними. Примеры названия роли: Content strategy, Content design, UX writing, ContentOps, Content marketing, Content management, Content engineering, Digital communications, Technical communications, Web content creation, Conversation design.

Планы на сентябрь

- Митап Good vs. Bad API Documentation: How API Documentation Drives Service Adoption. Бесплатно, онлайн.

- Вебинар What does documentation quality really mean and how do we improve it?. Бесплатно, онлайн.

- Секция докладов про документацию на конференции React Finland. Бесплатно, онлайн.

- Воркшоп Docs-as-code: An AsciiDoc primer на конференции DevConf US 2021. Бесплатно, онлайн.

#полезныессылки

Хелп Infracost

Что David Nunez (менеджер документации из Stripe) и Stephanie Blotner (менеджер технических писателей из Uber) улучшили бы в хелпе Infracost, потому что они рассказали про это в видео.

🌟 Не хватает домашней страницы

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

🌟Говорите про результат

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

🌟Проводите исследования

Чтобы определить работает ли документация, проводите пользовательские исследования. Во время исследований помните про то, какие бизнес задачи должна решать документация.

🌟Больше исследований

Можно проводить пользовательские исследования еще до начала разработки фичи. Так делает Stripe. Создайте документацию, которая описывает процесс работы с будущей фичей, и протестируйте ее на пользователях.

🌟Сценарии использования

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

🌟Не пытайтесь описать все сразу

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

🌟Документация часть продукта

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

#хелплинч #makedocumentationgreat

​​Интерактивные инструкции Algolia

У Algolia кроме привычных пошаговых инструкций есть интерактивный онбординг, который больше уже похож на интерфейс программы, чем на документацию.

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

Другие примеры динамической документации для разработчиков можно подсмотреть у Stripe и Worldpay.

#makedocumentationgreat #developerexperience

Swimm

Swimm — программа для создания документации. Позволяет встроить написание документации в процесс разработки. Такой подход называется Continuous Documentation. Например, можно вставить в документацию кусок кода, когда этот код изменится в исходнике, он изменится в документации. Кроме кусков кода можно вставить в документацию имена файлов или переменных, они тоже будут обновляться вместе с исходным кодом. Если какой-то документ стал не актуальным после изменений кода, то программа отметит его.

Есть плагины для VSCode и IntelliJ. При использовании плагина в коде будут видны ссылки на документацию. Документация открывается в IDE, то есть рядом с кодом, без переходов на другие сайты.

Интерфейс и некоторый фичи похожи на Confluence, например то, как код добавляется в документацию.

Сейчас Swimm в бета тестировании. Видео о том, как начать работать.

#тулзы

Краткое содержание. Сентябрь

- Видеообзор Docusaurus и Backstage.

- Новый Gatsby 4 работает быстрее и появился server side rendering.

- Советы по карьере от UX-писателей из Google, Airbnb и Spotify.

- Цикл статей про метрики для технического контента. В части 1 рассказывается о том, как задавать вопросы, на которые вы хотите, чтобы ваша аналитика отвечала, и о инструментах, которые могут помочь в этом. Часть 2 и часть 3 разбирают подход к аналитике на примере разделов начало работы и how to. В части 4 собраны проблемы, с которыми вы можете столкнуться, когда измеряете технический контент.

- Статья Научно обоснованный дизайн контента. Дизайн контента определяет как вы размещаете элементы на странице или экране. Дизайнерские решения могут или подрывать и отвлекать пользователей от идей, передаваемых контентом, или усиливать и поддерживать идеи.
Научно обоснованный дизайн контента — это методология создания контента, который согласуется с тем, как люди естественным образом воспринимают и обрабатывают информацию. Эта методология объединяет знания из таких областей, как исследования зрения и офтальмология, неврология, когнитивные способности и исследования внимания, психофизика и психология. Научно обоснованный дизайн контента помогает принимать решения по дизайну контента, которые естественным образом облегчают обработку информации. Это позволяет пользователям тратить свое время, усилия и когнитивные ресурсы на успешное использование информации для достижения целей, а не на расшифровку и интерпретацию контента.

- Видео Собираем документацию на основе программной модели. Пример создания документации к коду из комментариев с помощью Sphinx. Исходники на Github. Спасибо @mdanilov, что поделился.

Планы на октябрь

- Конференция Write the docs Prague 2021. Платно, онлайн.

- Конференция apidays LIVE LONDON 2021. Бесплатно, онлайн.

- Вебинар 5 lessons in achieving scale when you’re a solo strategist. Бесплатно, онлайн.

- Митап Findability in the world of docs. Бесплатно, онлайн.

- Рассылка Conversation Design Challenge. Бесплатно, онлайн.

#полезныессылки

​​Описание ошибок Plaid

В API документации Plaid большой раздел посвящен ошибкам. В нем есть список всех возможных ошибок и описание их формата. Такое можно часто встретить в документации API.

А вот что не часто можно встретить в API документации, так это детальное описание каждой ошибки, где есть:
- список методов, которые могут вернуть эту ошибку
- описание ошибки и почему она произошла
- пример ошибки
- чек-лист что делать с ошибкой

Еще из интересного в этой документации есть чек-лист для запуска проекта и диаграммы для объяснения user flow.

#makedocumentationgreat #developerexperience

The 2021 State of Software Quality

SmartBear опубликовали результаты опроса The 2021 State of Software Quality:

- 76% респондентов опроса используют стандарт OpenAPI.
- Самый популярный сервис для управления API — AWS API Gateway, но многие не используют ничего или создают собственные решения.
- Инструменты для создания документации API поднялись на 2-е место с 3-го в списке инструментов, которые нужны для создания API.
- Точная и подробная документация — это вторая по важности характеристика для API с точки зрения пользователей. А наиболее важные разделы в документации — это примеры, описание ошибок, аутентификация (тут все совпадает с результатами опросов прошлых лет).
- Большинство респондентов ответили, что в их компаниях есть формальный процесс документирования API. Утвердительно ответили как респонденты из крупных, так и из небольших компаний.
- Только 16% респондентов сказали, что у них есть технический писатель.

#developerexperience

Знаете ли вы, чего хотят ваши читатели?

Yoel Strimling провел несколько исследований, чтобы понять, что такое “хорошая документация” по мнению читателей и понимают ли это технические писатели.

1. Beyond Accuracy: What Documentation Quality Means to Readers
2. So You Think You Know What Your Readers Want?

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

В первом исследовании собраны различные методологии, по которым можно оценивать “хорошесть” документации. Из них выбрали методологию Wang and Strong (1996 года) и выделили 4 характеристики, в каждой определили подкатегории:

- Содержание: данные должны обладать качеством сами по себе (точность, достовернось, объективность, надежность).
- Контекст: данные должны рассматриваться в контексте поставленной задачи (объем, полнота, релевантность, своевременность, ценность).
- Представление: данные должны быть хорошо представлены (лаконичнось, согласованность, понятность, интерпретируемость).
- Доступность: данные должны быть легко извлекаемыми (доступность, безопасность).

Читателей попросили выбрать из подкатегорий те, которые они считают самым важным в документации (ссылка на опрос). Во втором исследовании, технических писателей попросили выбрать то, что они думают важно для читателей.

Какие выводы

Для читателей основные характеристики “хорошести” документации это:
- Точность
- Понятность
- Релевантность

И писатели выбрали их тоже. То есть писатели понимают, чего хотят читатели от документации.
Но есть критерий, который читатели оценили высоко, а вот писатели недооценили. Это ценность документации. Читатели хотят понимать, какую пользу принесет им документация, как она может не просто помочь им что-то сделать, а сделать это лучше.

#экспериментыналюдях

​​The F-word

Есть распространенный способ собирать фидбек у читателей — добавить в документацию вопрос “Помогла ли вам эта статья” или “Была ли полезна статья”. Задавая такой вопрос, сложно получить фидбек, который можно использовать, потому что информации не хватает.

В исследовании What Documentation Quality Means to Readers, кроме метрик “хорошести” документации, есть формула идеального фидбека. Фидбек должен быть содержательным и действенным (то есть его можно однозначно понять и применить).

Чтобы получить такой фидбек нужно задавать другие вопросы. Если следовать методологии Wang and Strong, то вопросы могут быть такие:
- Смогли ли вы найти информацию, которую искали?
- Была ли информация точной?
- Была ли информация легкой для понимания?
- Была ли информация релевантной?
Эти вопросы помогают измерить характеристики, которые читатели выбрали самыми важными в документации. Пример опроса из исследования.

Кроме самого исследования можно посмотреть видео или полистать презентацию выступления Yoel Strimling.

Краткое содержание. Октябрь

- Oпрос по зарплатам Write the Docs 2021. Принять участие можно до 20 декабря, результаты опубликуют в феврале 2022.

- Голосование DevPortal Awards 2021. Проголосовать можно до 7 ноября.

- Саммари API Specifications Conference 2021. В будущую спецификацию OpenAPI планируют включить Documentation driven development.

- Статья Chief Information Architect. Когда интернет только появился, люди, занимающиеся тем, что мы сейчас называем стратегией пользовательского опыта, исследованиями и дизайном, назывались информационными архитекторами. Сейчас роль информационного архитектора сводится или к выяснению навигации для сайтов, или к построению таксономии, онтологии, колец синонимов и прочего.
Есть много организаций, где никто не выполняет работу информационного архитектора для продукта в целом, даже если многие дизайнеры думают о информационной архитектуре своих проектов.Тем не менее кто-то в компании должен быть главным информационным архитектором и выполнять работу по отображению пространства проблем/возможностей, а также смысла и цели продукта в этой более крупной системе. Это может директор по продукту (CPO) или директор по дизайну (CDO).

- Статья Согласование содержания документации по продукту. Про то как SAP переделали свой сайт документации. Для этого они разобрались кто их целевая аудитория и что они ищут. Чтобы сгруппировать информацию в хелпе так, как ее легче будет найти пользователям, они использовали методику “сортировки карточек” — то есть попросили пользователей самих сгруппировать информацию, написанную на карточках, по категориям.

- Статья Content Operations 101. С точки зрения клиента компании имеют две задачи: сделать что-то полезное и сделать так, чтобы люди умели это использовать. Обучение клиента продукту — это контент. Продукт и контент нельзя разделить, потому что контент делает людей опытными пользователями продукта. Content Ops — это системы и процессы, которые эффективно передают контент от мозгового штурма команды к клиенту. Когда у ваших сотрудников есть согласованные процессы и системы, им не нужно думать о том, как их контент доходит до клиентов, они могут сосредоточиться исключительно на качестве контента.

Планы на ноябрь

- Церемония DevPortal Awards.Бесплатно, онлайн.

- Митап The Language of Care. Бесплатно, онлайн.

- Митап Docs for Developers: A conversation with the authors. Бесплатно, онлайн.

- Семинар Certified Simplified Technical English. Платно, онлайн.

- Митап Contract Technical Writing: A Survival Guide. Бесплатно, онлайн.

- Митап The Value of ML Documentation. Бесплатно, онлайн.

- Митап Social and Semantic Technical Documentation. Бесплатно, онлайн.

#полезныессылки

API Explorer DocuSign

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

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

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

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

#makedocumentationgreat #developerexperience

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 #тулзы

Эмоций разработчиков по отношению к документации

Группа ученых из университета 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. Я не считаю, что исследование дает полную картину, так как в нем учтены только те, кто внес изменения в документацию. Но мне было интересно узнать их эмоции и понравился подход.

#экспериментыналюдях

Краткое содержание. Ноябрь

- 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.

#полезныессылки

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

​​Какой длины делать обучающие видео?

Компания 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.

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

#экспериментыналюдях #самсебережиссер

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). Но точного понимания, как повлияет появление метавселенной на дизайнеров контента, пока нет.

Про редизайн документации GitLab - 2

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

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

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

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

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

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

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

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

#экспериментыналюдях

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

Как 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