1 марта 2019

В поисках идеальной документации

Сколько бы ни было статей на тему «Кто такой UX-аналитик», вопросы все равно остаются. Настало время рассказать об одной из задач аналитика — написании спецификаций.

Ideal documentation

Не секрет, что по одним только макетам команда разработки вряд ли сможет в полном объеме реализовать задуманную систему. На каждом этапе будут появляться все больше и больше вопросов «а как поведет себя система, если…». Чтобы их было как можно меньше, и нужна спецификация — один из подвидов технической документации наряду с тест-кейсами или описанием методов API, которая полностью определяет работу будущей системы. В идеальном мире. В нашем же идеальной спецификации не существует :) Тем не менее, можно стараться к ней приблизиться.

Для этого я посетила двухдневный курс Семена Факторовича «Advanced Technical Writing», где мы разбирали типичные структурные ошибки, пытались понять, что делать с субъективными, и целый день посвятили разбору и переписыванию текстов.

Этот курс вдохновил меня на проведение митапа с элементами интерактива на тему «В поисках идеальной документации» для своих коллег. Подготовка к нему помогла мне переосмыслить и интерпретировать материал курса для создания хорошей, полной спецификации. А на самом митапе мы смогли продуктивно обсудить весь процесс документирования в компании, т.к. были специалисты из разных отделов: от дизайнеров до тестировщиков!

Ideal documentation meetup

Для начала определились с тем, что же не так с документацией, как выглядит жизненный цикл документа. Это помогло понять, какие из этапов можно улучшить и оптимизировать. Далее поговорили про рецензирование, объективные (фактологические, орфографические, пунктуационные) и субъективные («мне не нравится», «я бы написал по-другому») ошибки и как с ними бороться.

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

Ideal documentation meetup

Но основной совет для тех, кто хочет научится создавать понятную для своей команды документацию, — это писать как можно больше, нарабатывать опыт и «заражаться хорошим текстовым вкусом». В этом вам может помочь чтение чужой документации (например, статей из техподдержки других компаний или спецификаций ваших коллег). А также прохождение интересных курсов от гуру-докторов технической документации. Большое спасибо Семену за вдохновение и наставление на истинный путь!

Если вы нашли ошибку, пожалуйста, выделите фрагмент текста и нажмите Ctrl+Enter.

Читайте в нашем блоге

Сообщить об опечатке

Текст, который будет отправлен нашим редакторам: