Diátaxis как ориентир в работе

Diátaxis помогает работать не только с содержанием документации, но и с процессом её создания.

Большинству авторов технической документации приходится решать, как организовать работу, непосредственно по ходу дела. Иногда документацию нужно однократно предоставить в полном и окончательном виде. Однако чаще работа над ней продолжается постоянно — например, параллельно с развитием продукта. Кроме того, многим авторам приходится улучшать или даже приводить в порядок уже существующий массив документации.

Подход Diátaxis к работе идёт вразрез со многими общепринятыми представлениями о документации. В частности, он предостерегает от планирования и движения сверху вниз, отдавая предпочтение небольшим итерациям, которые учитывают текущую ситуацию и постепенно складываются в общую картину.

Используйте Diátaxis как руководство, а не как план

Diátaxis даёт целостное представление о документации. Однако предложенная им структура — не план, который необходимо полностью реализовать в своей документации. Это руководство, карта, помогающая проверить, что вы находитесь там, где нужно, и движетесь в верном направлении.

Diátaxis предлагает способ осмыслить и понять свою документацию: какую задачу она выполняет и чего вы хотите с её помощью добиться. Инструменты Diátaxis позволяют оценить документацию, найти её проблемы и решить, как её улучшить.

Не беспокойтесь о структуре

Хотя структура играет в документации ключевую роль, использовать Diátaxis — значит не тратить силы на попытки сразу выстроить правильную структуру.

Если последовательно следовать подсказкам Diátaxis, документация со временем обретёт предложенную им структуру — но обретёт её потому, что стала лучше. Не наоборот: не нужно навязывать документации структуру, чтобы её улучшить.

Чтобы начать работать с Diátaxis, не нужно заранее делить документацию на четыре раздела. И уж тем более не следует создавать пустые разделы для учебных руководств, практических руководств, справочника и объяснений. Не делайте этого. Результат будет ужасен.

Вместо этого следуйте процессу, описанному в следующих двух разделах: вносите изменения там, где видите возможность улучшить документацию в соответствии с принципами Diátaxis. Так она начнёт постепенно приобретать определённую форму. В какой-то момент сделанные изменения словно потребуют перенести материал под один из заголовков Diátaxis — именно так и сформируется верхний уровень структуры. Иными словами, Diátaxis меняет структуру документации изнутри.

Работайте шаг за шагом

Diátaxis строго определяет структуру, но существующую документацию всегда можно улучшать итеративно, в каком бы состоянии она ни находилась — даже если по любым меркам в ней царит полный беспорядок.

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

Хотя Diátaxis даёт общую картину документации, не пытайтесь сразу работать над всей этой картиной. Это не нужно и не помогает. Diátaxis направляет небольшие шаги: продолжайте делать их один за другим, чтобы прийти к нужному результату.

Просто сделайте что-нибудь

Когда перед вами полный хаос, возникает искушение всё снести и начать заново. Не поддавайтесь ему. Чтобы улучшать документацию в соответствии с Diátaxis, необязательно специально искать недостатки. Лучше всего применять Diátaxis так:

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

Оцените выбранное. Теперь взгляните на этот фрагмент критически. Лучше, если он невелик: не больше страницы, а ещё лучше — один абзац или предложение. Проверьте его по критериям Diátaxis: Какую потребность пользователя он отражает? Насколько хорошо он её удовлетворяет? Что можно добавить, переместить, удалить или изменить, чтобы удовлетворить её лучше? Отвечают ли язык и логика требованиям этого типа документации?

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

Сделайте это. Выполните одно выбранное действие и считайте его завершённым: опубликуйте результат или хотя бы зафиксируйте изменение. Не думайте, что достойное улучшение требует чего-то ещё.

А затем вернитесь к началу цикла.

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

Позвольте работе развиваться органично

Стремясь к результату, мы склонны чередовать планирование с исполнением. Но это не единственный путь, и в работе с документацией часто находятся более удачные способы.

Здоровый органический рост

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

Авторские права на иллюстрацию принадлежат Линетт Воллер, 2021. Воспроизводится с любезного разрешения.

То же происходит с документацией: если следовать принципам Diátaxis, она обретёт здоровую структуру благодаря правильной организации внутренних компонентов. Подобно живому организму, она выстроит себя изнутри — по одной клетке за раз.

Полная, но не законченная

Рассмотрим растение. Как живой, растущий организм оно никогда не бывает законченным: всегда может развиваться дальше, переходить к следующей стадии роста и зрелости. Но на каждом этапе развития, от семени до взрослого дерева, оно всегда полноценно: в нём нет недостающих частей. В любой момент его состояние соответствует текущей стадии развития.

Точно так же документация никогда не бывает законченной: её приходится постоянно адаптировать к продукту и потребностям пользователей; при этом её всегда можно развивать и улучшать дальше.

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