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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

При прогоне тестов мы делаем в нужных местах скриншоты. Если они поменялись (определением поменявшести занимается

нетривиальный кусок кода), то создается MR в котором техпис может принять новые скриншоты и они вставятся в документацию.

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

кода и конфига, которые находятся в документации.

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

(определенные куски замазываются перед сравнением).

Этот кусок отвечает за достоверность документации.

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

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

Если документация написана так, что копипаста работает из коробки, это очень удобно. Этот подход иногда ухудшает читаемость.

Что мы здесь делаем сейчас? Учимся делать такие сниппеты, чтобы показывалось то, что существенно,

но при этом можно было скопировать полный рабочий пример.

Автоскриншоты

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

Пока гоняем тесты, cypress (инструмент для браузерного тестирования) может сделать скриншот с какого-нибудь html элемента.

Его в принципе можно сравнить с предыдущим скриношотом (screenshot-based тестирование), но это не самое интересное.

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

и в случае если они обновились, делает merge request, а техпис может их очень удобно в гитлабе смержить.

Интеграция с хелпом

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

Интеграция с хелпом подразумевает, что некоторые кусочки документации (особенно возле скриншотов) помечаются какими-то тегами,

при процессинге документации выгружаются наружу в виде json файла, который потом отдается в react-админку нашего софта.

Там этот json-хелп превращается в всплывающие по нажатию на иконку вопроса подсказки, разбросанные по всей админке.

В самой админке есть скрипт, который обходит весь яваскрипт 

Что планируется

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

* автоматические скринкасты

* проверка полноты документации

* миграция на стандартные инструменты

Автоскринкасты

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

Что делает тестировщик?  Руками выполняет какие-то операции и проверяет результат.

Что делает человек при записи скринкаста?  Руками выполняет какие-то операции и записывает эти действия.

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

Почему нельзя научить робота записывать скринкасты? Мы сейчас учим, планируем через гугл озвучивать.

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

Проверка полноты

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

У нас есть полная JSON-схема всего конфига. Мы разметить всю документацию путями из этого конфига и тем самым получить

полную информацию хотя бы о покрытии конфига документацией.

Аналогичный подход можно применить и для API, явно сигнализировав, какие методы и поля покрывает конкретный текст и пример.

Тут можно фантазировать и добавлять автоматизации, но начинаем с этого.

Foliant

========

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

Из маленьких заметок: одностраничную документацию не рассматриваем в принципе, это какое-то нелепое пионерство, не имееющее никакого смысла сегодня.

PDF очень нужен, потому что сейчас он у нас очень плохо генерируется с помощью prawn.