Какая бывает документация

[rewiaca]

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

А вопрос с поддержкой актуальности доки решается, например, на уровне комитов в git, если это софтверный продукт. Каждый комит затрагивает уже описанные ранее функции продукта или создает новое описание.

[Molechka]

Мне кажется, ваш вопрос больше к аналитикам ))
Но в любом случае это примерно как «есть ли какой-то подход, как описывать тесты, по типу: пишем чек-листы, но иногда...». Ответ — нет, нет такого подхода, каждая команда решает для себя, как ей будет удобнее

[rewiaca]

Видимо, я не уловил методологической значимости в вашей публикации.

[Molechka]

Она описана в первых двух абзацах в начале статьи и в «итого» тоже сразу же)

[Sergey-Titkov]

Посмотрите в сторону www.madcapsoftware.com или его open source аналогов

[rewiaca]

Благодарю. Собираю как раз некий фреймворк, который кушает текста в wiki/html разметке и структурирует общую базу знаний, а потом делает экспорта в виде faq/docs/blog posts/referat/etc

[saboteur_kiev]

Текст на кнопке — тоже документация

Разве в данном случае не интерфейс?

[Molechka]

А текст в поп-апах, на главной странице сайта, в полях для ввода — это тогда тоже интерфейс. Что не мешает тексту оставаться документацией. Просто описана она не в вики-системе, а в интерфейсе

[saboteur_kiev]

Ну не знаю. Документация и интерфейс — имхо по терминологии разные вещи.

[Molechka]

Да, и именно поэтому когда начинающий тестировщик тестирует документацию, в его понимании это ограничивается только «проверить ТЗ». А проверить стоит кучу всего ещё. Можно, конечно, идти строго по определенной классификации, но тогда как он поймет, что ему проверять при тестировании интерфейса?

[DjPhoeniX]

В идеальном мире, тестировщик должен действовать как в том самом анекдоте:

Заходит однажды...

Заходит однажды тестировщик в бар.
Забегает в бар.
Пролезает в бар.
Танцуя, проникает в бар.
Крадется в бар.
Врывается в бар.
Прыгает в бар.
Телепортируется в бар.

и заказывает:

кружку пива,
2 кружки пива,
0 кружек пива,
999999999 кружек пива,
ящерицу в стакане,
–1 кружку пива,
NaN кружек пива,
NULL кружек пива,
qwertyuip кружек пива.

[saboteur_kiev]

При тестировании интерфейса — тестировать интерфейс.
При тестировании ТЗ — проверять документацию.
И не путать документацию и интерфейс =)

[Molechka]

То есть описание «что нужно заполнить в этом поле», написанное в отдельной вики-система — это документация, а написанное около поля ввода — нет?

[Molechka]

Клево, то есть если описание что заполнить в поле и как написано около поля, то все пользователи и тестировщики должны бегать к аналитику и кричать, что вообще не в курсе, о чем поля и какие там ограничения, ведь «у нас нет никакой информации, дайте нам ВОРД файл, а ИНТЕРФЕЙС мы читать не будем»?

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

А вы реально не знаете, что разные классификации пересекаются?

[saboteur_kiev]

Тогда такой вопрос:
Если в программе в интерфейсе на кнопке написано «ОК» а в документации написано «ДА», это баг где — в программе или в документации?

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

[Molechka]

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

Впрочем, «ок» или «да» обычно даже заведения бага не стоит.
А если что-то более сложное, то вполне может быть, что в доке устарело, разработчик потом с аналитиком перетер и сделали по другому, исправить документацию упс, забыли.

Так что однозначного ответа на ваш вопрос нет. Зависит от ситуации.

[Molechka]

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

[saboteur_kiev]

Ну если уж такая пьянка.

Я задал простой вопрос — как определить где нужно исправить, если в документации пользователя и интерфейсе описание кнопки разнится?

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

Давайте я в ответ уточню с примером посложнее:
Например, если я буду пользоваться не простеньким веб-сайтом, а программой, где нажатие такой кнопки приводит к каким-то серьезным последствиям (например программа управления медицинским оборудованием, выполнение которой может привести к смерти пациента), и выполнять действия по инструкции со скриншотами, то увидев на скриншоте ДА, а на экране ОК, я не буду полагаться на свою интуицию. И следовательно вопрос — как определить что нужно исправлять — программу или документацию.

Судя по вашему посту, интернет-магазином пользоваться просто нельзя.

Вы же вроде работаете профессиональным тестировщиком. У вас баги не делятся на критичные и минорные (последние можно даже «исправлять» статусом «Won't fix»)

[Molechka]

Ну вот видите, вы и сами в состоянии привести разные примеры, где полагаемся на интуицию, а где нет :)

[saboteur_kiev]

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

Это очень полезно знать.

[moonster]

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

[Molechka]

Это да, но это тема для другой статьи))