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

Поташников Николай, ООО «КУРС-ИТ»

Вместо введения

Пример документированного скрипта БД

/**Учет курсов валют*/
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
);

То же самое, но более дружелюбно

db structure unite
db structure unite html

Общая схема преобразования

Код, осуществляющий изменение БД

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

Выходной формат (html, pdf, презентация, электронная книга)

В структуре документации

Например так

  • Описание организации информационной базы

    • Физическая структура

      • Учет курсов валют

  • Пояснительная записка к техническому проекту

    • Основные технические решения

      • Решения по составу информации

        • Учет курсов валют

  • …​

Если использовать Asciidoc

include

В отчете о проделанной работе

  • Перечень выполненных работ

    • Доработан (разработан) модуль учета валют

      Перечень обновленной документации приведен в приложении 1

    • …​

  • Приложение 1. Доработанные документы в части модуля «Учет курсов валют»

    • Физическая структура базы данных

    • …​

Принцип единого источника

В примере источник документации один, остальное — представления

Организация процесса документирования

Типовой подход к организации документирования

Разделение процессов документирования и кодирования

soft vs doc component
soft vs doc component fire
norstein

Применение практики непрерывной интеграции (CI)

Наличие документации должно входить в definition of done (definition of ready)

Зависимости

soft with doc component

Что можно улучшить?

Документация в коде

Типовой проект

  • Схема базы данных — в коде

  • API (REST, SOAP) — в коде

  • Программа и методика испытаний — в коде и отдельных документах

  • Эксплуатационная документация — в отдельных документах и в коде

Автоматическая проверка качества документации

Примеры того, что можно проверить

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

  • Документация собирается

  • Отсутствуют слова из стоп-листа (упоминание других заказчиков)

  • Оформление текста (висячие предлоги; заголовки, отрывающиеся от текста и т.п.)

Важность pdf

  • Позволяет объединить все содержание в компактный кросс-платформенный формат

  • Позволяет передать документацию на согласование

Pdf с примечаниями

acrobat comment

Выводы

  • Используйте принцип единого источника

  • Держите документацию поближе к коду, лучше в коде

  • Включайте наличие документации в definition of done

  • Самый простой формат согласования документации — pdf

Полезные ссылки