Документация на сайте
Немножко хочу рассказать про документацию на нашем https://flussonic.com/doc/
Основные идеи, которые сейчас я принял при развитии документации такие:
* документация — такой же кодифицируемый кусок продукта, как и сценарий тестирования
* надо учиться проверять документацию на полноту и достоверность
* тестировщик, техпис и продакт делают в некотором смысле схожие действия с софтом: проходят по определенным сценариям
Текущий статус
=============
Сейчас это по 2 мегабайта текста на английском и русском, 280 файлов каждого языка, порядка 150 тыс слов/около миллиона знаков
Документация по большей части референс, т.е. сухое описание фич, их настроек и т.п.
Сейчас она обрабатывается на руби маркдауном, потом написанным нами xml процессором, который делает ряд вещей:
1. проставляет title будущим HTML-ям и метатеги для SEO
2. обрабатывает инклюды
3. обрабатывает ссылки
4. делает магию с документационными тестами
5. делает магию с интеграцией с хелпом в приложении
Документационные тесты
======================
Документационные тесты — я не видел описания подобной идеи, придумали сами, скорее всего многие такое уже делали.
Идея в следующем: у нас в документации есть сниппет кода/конфига, значит надо быть уверенным в том,
что он правильный и рабочий.
Решение: рядом с документацией кладем тест, который по нужному идентификатору извлекает из текста документации
нужный кусочек, вставляет его куда-то и выполняет тест. Результат сверяет с тем, что написано в документации.
Если что-то разошлось, мы узнаем.