October 20th, 2020

Документация на сайте

Немножко хочу рассказать про документацию на нашем https://flussonic.com/doc/


Основные идеи, которые сейчас я принял при развитии документации такие:


* документация — такой же кодифицируемый кусок продукта, как и сценарий тестирования

* надо учиться проверять документацию на полноту и достоверность

* тестировщик, техпис и продакт делают в некотором смысле схожие действия с софтом: проходят по определенным сценариям




Текущий статус

=============


Сейчас это по 2 мегабайта текста на английском  и русском, 280 файлов каждого языка, порядка 150 тыс слов/около миллиона знаков


Документация по большей части референс, т.е. сухое описание фич, их настроек и т.п.


Сейчас она обрабатывается на руби маркдауном, потом написанным нами xml процессором, который делает ряд вещей:


1. проставляет title будущим HTML-ям и метатеги для SEO

2. обрабатывает инклюды

3. обрабатывает ссылки

4. делает магию с документационными тестами

5. делает магию с интеграцией с хелпом в приложении







Документационные тесты

======================




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


Идея в следующем: у нас в документации есть сниппет кода/конфига, значит надо быть уверенным в том,

что он правильный и рабочий.


Решение: рядом с документацией кладем тест, который по нужному идентификатору извлекает из текста документации

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

Если что-то разошлось, мы узнаем.


Collapse )