Тестирование документации к программным продуктам

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

Перечень качеств, на которые можно ориентироваться при тестировании документации:


1. Работоспособность сценариев


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

2. Полнота описания


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

3. Уделение внимания обязательным пунктам


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

4. Актуальность описания


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

5. Адаптированность к тому, что пользователь будет в спешке


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

6. Адаптированность к тому, что пользователь будет раздражен


Эмоциональная реакция при взаимодействии с программными продуктами имеет очень большое сходство с реакцией при взаимодействии с другими людьми. В случае, если пользователь читает документацию из-за того, что у него возникли какие-либо неполадки, скорее всего он будет в раздраженном состоянии. Здесь можно рекомендовать делать атомарность предложений и абзацев. Например, вместо <<Переустановите приложение, если возникают неполадки при использовании. Неполадки возникают когда установлен компонент-1 операционной системы, и в настройках операционной системы задано условие-2.>> лучше прописать <<Если установлен компонент-1 операционной системы и в настройках операционной системы задано условие-2, то в приложении могут возникнуть неполадки, решить которые можно лишь переустановкой.>>

7. Структурированность, адаптированность к быстрому поиску


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

8. Наличие указания на необратимость действий


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

9. Подтверждение ожидаемого


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

10. Описание последствий отсутствия действий пользователя


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

11. Ясность изложения информации


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

12. Логика и согласованность


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

13. Последовательность изложения


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

14. Орфография, синтаксис, пунктуация


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

15. Наличие описания настроек по умолчанию


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

16. Адаптированность к аудитории


Если продукт рассчитан на простых пользователей, то в документации к нему действия пользователя должны описываться простыми понятными терминами. Если же продукт рассчитан на пользователей Apple либо на администраторов Linux, то стоит учитывать особенности этих пользователей. Руководства к серверному и управляющему ПО часто ориентированы на системных администраторов.

17. Атомарность сценариев


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

18. Адаптированность к наименее возможной квалификации пользователей


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

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


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

Выгоду от наличия документации можно сравнить с выгодой создания дополнительной инфраструктуры при постройке жилья. С одной стороны, при продаже главную роль играет площадь жилья: цена назначается за квадрат. Но если присмотреться — цена в некоторых домах значительно превосходит цену в других. И обусловлено это в первую очередь окружающей инфраструктурой (стоянки, лифты, газоны, и т.д.).

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

Подробнее
Реклама
Комментарии 19
  • +3
    Из-за названия статьи я сначала подумал, что вы какое-то автоматическое тестирование настроили.
    А статья грамотная, всё по полочкам разложено. Я бы назвал её списком требований к хорошему документу.
    • +1

      Полная документация может иметь внушительный размер. И на нескольких языках. Как поставлен процесс проверки, чтобы ничего не упустить, не забыть. Проверяете печатный документ или цифровой? Система контроля версий? Есть привязка к багтрекеру продукта? Что-то проверяется автоматизированно? Может какая-то CMS или "фреймворк" используется из которых компилируется документ?

      • 0
        Проверяется цифровой документ. Автоматизировать по-хорошему тут можно только проверку орфографии. Разумеется, есть автоматизированная система, в которой ведется работа над документацией, но пользоваться мне ей не доводилось, могу лишь сказать что все очень хорошо организовано.
        • 0
          А назвать можете? Или это внутренняя разработка?
          • 0
            К сожалению, не готов назвать (чту договор с работодателем о неразглашении информации о компании).
          • 0
            Можно автоматизировать проверку на вот такие косяки:

            • битые ссылки
            • отсутствующие картинки
            • наличие стоп-слов (жаргон, нецензурные слова)
            • наличие неверных символов (н-р, русская буква «с» вместо англоязычной «c»)
            • ошибки оформления (термины не выделены полужирным или предложение с маленькой буквы написали)

            Ну и на что фантазии хватит. Но, конечно, такие вещи лучше проверять на исходниках документации (md, xml, html и т.д.), а не на скомпилированных документах.
        • +1
          Полезное правило в документации: за деепричастный оборот расстрел на месте, предложение с тремя запятыми и более — штраф или объяснительная. Вообще, писать надо как для слегка умственно отсталого. Лучше повториться, чем допустить неясность. Вообще, красота текста документации — зло, требуется невозможность неправильного толкования.
          • +1
            Господи как же я раньше-то читал документацию с деепричастными оборотами, и тремя и более запятыми! Спасибо, что просвятили. Больше не буду такого делать.
            • 0
              Читать можно, но использовать деепричастный оборот в технической документации не желательно.
          • 0
            А какие-то инструменты ведения документации можете оценить на базе своего опыта? Очень интересно.
            • 0
              Неа, инструментами ведения документации пользоваться не доводилось. Лишь тестировал качество.
              • +2

                В компании используем asciidoctor + uml (asciidoctor-diagram).
                Исходники документации в git, сборка и версионирование средствами gradle (исторически сложилось, т.к. документацию изначально писали программисты; оказалось удобно), до этого был maven.
                Сборка в pdf (также есть html, но мы его не используем), каждый файл получает в имени номер версии (во избежание путаницы у получателя).
                Из приятных удобняшек — один исходник используется для двух сборок — одна xml-api, другая json (по сути различается примерами запросов-ответов). Используется условный оператор.

                • 0
                  Большое спасибо, что поделились — как выяснилось, такой инструмент, как asciidoctor, прошёл мимо меня. Лень, конечно, заморачиваться с Ruby, ибо это совершенно чужой для меня инструмент, но надо попробовать. Возможно, сборка в PDF и HTML одновременно + читабельность исходных файлов того стоят.
              • +1
                Спасибо за статью: подробно, лаконично, легко проверять свои тексты при подготовке пакета документации по такому чек-листу!
                • +1
                  По поводу качества документации я для себя решил за «точку отсчета» взять ГОСТы класса 19 (ЕСПД – Единая Система Программной Документации) и уже от неё «работать напильником». Где-то больше, где-то меньше – в зависимости от требований заказчика (для конечных пользователей – один вариант, для ИТ-специалистов – расширенный вариант).
                  А за статью – спасибо!
                  • 0
                    Это хорошо когда за документацию отвечают специально обученные (с отдельным ФОТ) люди. Бывает разработчики ПО пишут документацию по ГОСТ, ведущие специалисты проверяют/тестируют, затем руководители проверяют/тестируют, затем заказчик. Это такой отдельный Ад по превращению разработчиков в «Программистов Word за 3 года», не надо так.
                    • +1

                      Можно добавить:


                      • однородность. В том смысле, что если используются специальные термины — везде используются одни и те же, а не синонимы. Если есть стилистические приемы (например, куски xml-запросов или оформление кодов ошибок) — везде оформлены в одном стиле. Проблема особенно актуальна, когда документацию ведет несколько человек
                      • википедичный стиль изложения. В частности, изложение исключительно от третьего лица.
                      • список изменений, версия документа
                      • если речь идет о каких-либо интеграциях — всегда прилагать пример запросов-ответов или прочих вызовов. Это существенно упрощает понимание текста.
                      • 0
                        Здорово, эти же принципы можно и к любой документации приложить (например, которая пишется тестировщиками для тестировщиков).
                        • 0
                          За статью — риспект.
                          От себя добавлю, что для написания и требований и тестов и документации всегда использую еще одно золотое правило: «Всё, что МОЖЕТ быть неправильно понято — БУДЕТ неправильно понято!»
                          Ну и структурированность очень важна, да.

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

                          Самое читаемое