Применение практики «Документация как код» для документирования заказных приложений

Николай Поташников
Руководитель проектов, КУРС

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

Наш 20-летний опыт создания заказных приложений позволяет с уверенностью сказать, что практика «Документация как код» является наилучшей для сокращения усилий при документировании, причем как в маленьких, так и в очень больших проектах с любым уровнем формализации требований. В докладе я расскажу о том, как эта практика применяется у нас в компании. В своей работе мы ориентируемся на технологическую цепочку Asciidoctor, но речь пойдет об общем подходе к процессу подготовки программной документации, его организационной и технологической составляющих.

Transcript

1. «ДОКУМЕНТАЦИЯ КАК КОД» ДЛЯ ЗАКАЗНЫХ ПРИЛОЖЕНИЙ Поташников Николай, ООО «КУРС-ИТ» 1
2. ВМЕСТО ВВЕДЕНИЯ 2 . 1
3. ПРИМЕР ДОКУМЕНТИРОВАННОГО СКРИПТА БД /**Учет курсов валют*/ CREATE GRAIN rate VERSION '1.0'; /**Перечень валют*/ CREATE TABLE Сurrency ( /**Аббревиатура валюты*/ abbr VARCHAR(3) NOT NULL PRIMARY KEY /**Наименование валюты*/ ,name VARCHAR(20) NOT NULL ); /**Курс валют по дням*/ CREATE TABLE Rate ( currency_abbr VARCHAR(3) FOREIGN KEY REFERENCES Currency(abbr) /**Дата*/ ,date DATETIME NOT NULL /**Курс*/ ,rate DECIMAL(10,2) NOT NULL ); 2 . 2
4. ТО ЖЕ САМОЕ, НО БОЛЕЕ ДРУЖЕЛЮБНО 2 . 3
5. 2 . 4
6. 2 . 5
7. ОБЩАЯ СХЕМА ПРЕОБРАЗОВАНИЯ Код, осуществляющий изменение БД  Markup для документирования (мы используем Asciidoc)  Выходной формат (html, pdf, презентация, электронная книга) 2 . 6
8. В СТРУКТУРЕ ДОКУМЕНТАЦИИ Например так Описание организации информационной базы Физическая структура Учет курсов валют Пояснительная записка к техническому проекту Основные технические решения Решения по составу информации Учет курсов валют … 2 . 7
9. ЕСЛИ ИСПОЛЬЗОВАТЬ ASCIIDOC 2 . 8
10. В ОТЧЕТЕ О ПРОДЕЛАННОЙ РАБОТЕ Перечень выполненных работ Доработан (разработан) модуль учета валют Перечень обновленной документации приведен в приложении 1 … Приложение 1. Доработанные документы в части модуля «Учет курсов валют» Физическая структура базы данных … 2 . 9
11. ПРИНЦИП ЕДИНОГО ИСТОЧНИКА  В примере источник документации один, остальное — представления 2 . 10
12. ОРГАНИЗАЦИЯ ПРОЦЕССА ДОКУМЕНТИРОВАНИЯ 3 . 1
13. ТИПОВОЙ ПОДХОД К ОРГАНИЗАЦИИ ДОКУМЕНТИРОВАНИЯ  Разделение процессов документирования и кодирования 3 . 2
14. 3 . 3
15. ПРИМЕНЕНИЕ ПРАКТИКИ НЕПРЕРЫВНОЙ ИНТЕГРАЦИИ (CI)  Наличие документации должно входить в definition of done (definition of ready) 3 . 4
16. ЗАВИСИМОСТИ 3 . 5
17. ЧТО МОЖНО УЛУЧШИТЬ? 4 . 1
18. ДОКУМЕНТАЦИЯ В КОДЕ Типовой проект Схема базы данных — в коде API (REST, SOAP) — в коде Программа и методика испытаний — в коде и отдельных документах Эксплуатационная документация — в отдельных документах и в коде 4 . 2
19. АВТОМАТИЧЕСКАЯ ПРОВЕРКА КАЧЕСТВА ДОКУМЕНТАЦИИ Примеры того, что можно проверить Документация есть Документация собирается Отсутствуют слова из стоп-листа (упоминание других заказчиков) Оформление текста (висячие предлоги; заголовки, отрывающиеся от текста и т.п.) 4 . 3
20. ВАЖНОСТЬ PDF Позволяет объединить все содержание в компактный кросс-платформенный формат Позволяет передать документацию на согласование 5 . 1
21. PDF С ПРИМЕЧАНИЯМИ 5 . 2
22. ВЫВОДЫ Используйте принцип единого источника Держите документацию поближе к коду, лучше в коде Включайте наличие документации в definition of done Самый простой формат согласования документации — pdf 6
23. ПОЛЕЗНЫЕ ССЫЛКИ  — простой редактор для Asciidoctor  — инструмент управления структурой БД со встроенными возможностями документирования  — шаблон для создания pdf  — еще шаблон для создания pdf Как со мной связаться @nmpotashnikoff AsciidocFX https://github.com/CourseOrchestra/2bass https://github.com/CourseOrchestra/course-doc https://bitbucket.org/Lab50/espd-docbook5/src/ nm@potashnikoff.net 7