К теории качества в документации

Diátaxis - это подход к качество в документации.

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

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

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

Функциональное качество

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

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

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

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

Глубокое качество

Есть и другие характеристики, которые мы можем назвать Глубокое качество.

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

Подумайте о таких характеристиках, как:

• Чувствовать себя хорошо использовать

• иметь поток

• удовлетворять человеческие потребности

• быть красивой

• Предвидеть пользователя

В отличие от характеристик функционального качества, они не могут быть проверены или измерены, но все же могут быть четко идентифицированы. Когда мы сталкиваемся с ними, мы обычно (не всегда, потому что мы должны быть способны на это) распознаем их.

Они являются характеристиками Глубокое качество.

В чем разница?

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

Документация может отвечать всем требованиям функционального качества, но при этом не обладать глубоким качеством. Существует множество примеров документации, которая является точной и последовательной (и даже очень полезной), но в то же время неудобной и неприятной в использовании.

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

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

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

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

Наконец, все характеристики функционального качества предстают перед нами, как создатели документации, как бремена и ограничения. Каждый из них представляет собой испытание или вызов, который мы можем потерпеть неудачу. Или, даже если мы встретили один теперь, мы никогда не сможем отдохнуть, потому что следующий релиз или обновление означает, что нам придется еще раз проверить нашу работу. С другой стороны, такие характеристики, как предвосхищение потребностей или потока, представляют собой освобождение, произведение творчества или вкуса. Чтобы достичь функционального качества в нашей работе, мы должны соответствовать к ограничениям; для достижения глубокого качества мы должны изобретать.

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

Как распознать высокое качество

Рассмотрим, как мы оцениваем качество, скажем, одежды. Одежда должна иметь функциональное качество (они должны держать нас соответственно теплыми и сухими, вставать, чтобы носить). Эти вещи объективно измеримы. Вам не нужно много знать об одежде, чтобы оценить, насколько хорошо они это делают. Если вода попадает внутрь, или одежда разваливается — ей не хватает качества.

Есть и другие характеристики качества одежды, которые не могут быть просто измерены объективно, и чтобы распознать эти характеристики, мы должны иметь представление об одежде. Качество материалов или изготовления не всегда сразу очевидно. Умение судить о том, что предмет одежды хорошо висит, хорошо двигается или был умело сформирован, требует разработки хотя бы базового взгляда на эти вещи. И это его характеристики Глубокое качество.

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

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

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

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

Производство качественной работы зависит от нашей способности это сделать.

Диатаксис и качество

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

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

Выявление недостатков в функциональном качестве

Хотя Diátaxis не может обращаться к функциональному качеству давать, он все равно может его обслуживать.

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

Например, подход Diátaxis рекомендует использовать архитектура справочной документации должна отражать архитектуру кода, который она документирует;. Это делает пробелы в документации более заметными.

Или перемещение объяснительного словаря из учебного пособия (в соответствии с требованиями Диатаксиса) часто приводит к выделению раздела, в котором читателю было предоставлено что-то для себя.

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

Создание глубокого качества

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

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

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

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

Диатаксис сохраняет поток, помогая предотвратить нарушение ритма, которое происходит, когда что-то пересекает нашу цель и неуклонно продвигается к ней (например, когда отступление в объяснение прерывает руководство).

И так далее.

Понимание границ

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

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

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

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