Пирамида рецензирования

В разработке документации есть этапы (слои) рецензирования. Это порядок проверки документа, он примерно такой:

— сам перечитал и проверил на грубые ошибки;
— отдал коллеге на проверку грамотности, структуры и стиля;
— отдал эксперту на проверку смысла и содержания.

Если на конкретном этапе есть замечания, документ возвращают доработку, а не передают дальше.

А в тестировании есть понятие «пирамида тестирования». Тесты выполняются в таком порядке:

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

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

Это я в который раз намекаю, что документация — это продукт ))

Или неотъемлемая часть продукта

Ну да

Думаю все же продукт )

Привет! Ты точно знаешь про пирамиду тестирования ))

👋

Привет! Знаю немного, но интересно на неё с разных сторон посмотреть, так что заинтересовался поднятой тобой темой :)

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

На WTD Prague 18 был доклад про инструмент, который вытаскивает примеры кода из markdown и выполняет их. Так они пишут документацию по развертыванию системы, этим инструментом ее тестируют и при желании могут и на бою использовать.

С другой стороны они, конечно, изобрели свой убогий, негибкий и бедный фичами Ansible ))

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

В питончике есть вот такое:
https://docs.python.org/3.7/library/doctest.html

Где-то рядом тихо плачет LiterateHaskell, doctest и маячит тень Кнутовского (?) Literate Programming

и не только в питоне. Например, http://hackage.haskell.org/package/doctest

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

мы в tarantool всякие библиотеки документируем, много. и автотестов на код в доке не пишем. и огребаем за это баг-репорты при изменении кода временами. надо подумать мысль про автотесты, спасибо

Кажется, может сработать такой вариант: код в отдельных файлах, которые включаются (include) в текстовую доку. И отдельно — автотесты на этот код.

+

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

Как про джаву каждый раз писать static final void main() {...}