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, ваша документация приобретет здоровую структуру, поскольку ее внутренние компоненты сами по себе хорошо сформированы - как живой организм, она выстроится изнутри наружу, по одной клетке за раз.

Полный, не законченный

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

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

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