Собака Павлова
Сто шпаргалок Технологии и разработка Как писать документацию к интерфейсам

Как писать документацию к интерфейсам

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

#документация #интерфейсы #технический писатель

Три главных предмета в фокусе внимания

  1. Потребитель документации

    Кому она нужна? Следующему дизайнеру, разработчику, QA, аналитику, пользователю?

  2. Интеграция с результатом

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

  3. Сама необходимость документации

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

5 советов,
как делать хорошо

  1. Не делайте

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

  2. Наведите порядок в макетах

    Хорошо структурированные макеты и внятные комментарии избавляют от необходимости дополнительно документировать дизайн.

  3. Смиритесь с тем, что документация меняется

    Синхронизация документов с макетами — дикая проблема. Лучше даже не пытаться.

  4. Подходите к докментации, как к интерфейсу

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

  5. Привлеките технического писателя

    Если работа с буквами неизбежна (например, это требование договора), то пусть ее делает специально обученный человек. Это не менеджер и не дизайнер.

Например

ВидеоДедМороз

Иллюстрировали поведение интерфейса прямо в макетах.

Симетра

Аудит интерфейса — частный случай документации, которая действительно нужна.

Хороший образец

Пример «самодокументируемого» проекта, где без лишних букв понятно, что как работает.

Приложение для проверки и подписи документов

Так делать не надо

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

Инструменты

Figma

Выжмите из нее все. Дерево фреймов, dev-mode, секции, комментарии, стрелочки и подписи.

Jira

Часто макеты сразу превращаются в таски, минуя этап документирования.

Любая википодобная система

Например, Notion. Чтобы сразу писать задать структуру и перелинковать разделы между собой.

Технический писатель

Если не можете привлечь, хотя бы проконсультируйтесь

Написание документации — отличный повод попрактиковаться в делегировании.

Евгений Романовский, руководитель проектного офиса «Собаки Павловой»

Другие шпаргалки

Ищете подрядчика или команду?

Давайте обсудим вашу задачу.

Хотите у нас научиться?

1000+ упражнений по дизайну интерфейсов.