Shut up and write

2021-11-05 14:00:22 Краткое содержание. Октябрь

- 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. Бесплатно, онлайн.

#полезныессылки Открыть/Комментировать

2021-10-29 14:00:06 ​​The F-word

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

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

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

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

2021-10-15 14:00:11 Знаете ли вы, чего хотят ваши читатели?

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 характеристики, в каждой определили подкатегории:

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

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

Какие выводы

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

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

#экспериментыналюдях Открыть/Комментировать

2021-10-08 14:00:17 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 Открыть/Комментировать

2021-10-01 14:00:51 ​​Описание ошибок Plaid

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

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

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

#makedocumentationgreat #developerexperience Открыть/Комментировать

2021-09-24 12:00:51 Краткое содержание. Сентябрь

- Видеообзор 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. Бесплатно, онлайн.

#полезныессылки Открыть/Комментировать

2021-09-17 12:01:01 Swimm

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

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

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

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

#тулзы Открыть/Комментировать

2021-09-10 14:00:07 ​​Интерактивные инструкции Algolia

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

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

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

#makedocumentationgreat #developerexperience Открыть/Комментировать

2021-09-03 14:00:57 Хелп Infracost

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#хелплинч #makedocumentationgreat Открыть/Комментировать

2021-08-27 14:00:16 Краткое содержание. Август

- В 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. Бесплатно, онлайн.

#полезныессылки Открыть/Комментировать