Как писать документацию к интерфейсам
Желание сделать документацию к интерфейсам — рефлексивное, но чаще всего бессмысленное. Важно понять, зачем и кому эта документация нужна и как обойтись без нее. Почти наверняка аккуратно структурированных макетов будет достаточно. А если нет, то лучше всего поручить дело техническому писателю.
Три главных предмета в фокусе внимания
-
Потребитель документации
Кому она нужна? Следующему дизайнеру, разработчику, QA, аналитику, пользователю?
-
Интеграция с результатом
Близость документации к тому, что вы описываете. Документация должна лежать рядышком с макетами.
-
Сама необходимость документации
Усилий много, а толку может и не быть. Часто макетов достаточно, они сами по себе документация.
5 советов,
как делать хорошо
- Не делайте
Скорее всего она никому не нужна. Очень часто желание сделать документацию — это рефлекс. Да, можно сделать. Да, мы тоже делали. Нет, это почти никогда не нужно. Самые разные команды разработки прекрасно обходились без документации к нашим интерфейсам и сами просили нас не тратить на нее время.
- Наведите порядок в макетах
Хорошо структурированные макеты и внятные комментарии избавляют от необходимости дополнительно документировать дизайн.
- Смиритесь с тем, что документация меняется
Синхронизация документов с макетами — дикая проблема. Лучше даже не пытаться.
- Подходите к докментации, как к интерфейсу
Например, если разработчкам нужна документация, чтобы начать работать, лучше оформить ее как набор задач в бэклоге, а не как единый документ. Если нужна не столько документация, сколько презентация — ее и делай.
- Привлеките технического писателя
Если работа с буквами неизбежна (например, это требование договора), то пусть ее делает специально обученный человек. Это не менеджер и не дизайнер.
Например
Хороший образец
Пример «самодокументируемого» проекта, где без лишних букв понятно, что как работает.
Так делать не надо
Попытка держать полную и синхронизированную с изменяющимся прототипом текстовую документацию, просто чтобы было. Это невозможно.
Инструменты
Выжмите из нее все. Дерево фреймов, dev-mode, секции, комментарии, стрелочки и подписи.
Часто макеты сразу превращаются в таски, минуя этап документирования.
Любая википодобная система
Например, Notion. Чтобы сразу писать задать структуру и перелинковать разделы между собой.
Технический писатель
Если не можете привлечь, хотя бы проконсультируйтесь
Написание документации — отличный повод попрактиковаться в делегировании.
Евгений Романовский, руководитель проектного офиса «Собаки Павловой»
Другие шпаргалки
Ищете подрядчика или команду?
Давайте обсудим вашу задачу.
Хотите у нас научиться?
1000+ упражнений по дизайну интерфейсов.
eduhund.com