После разработки схемы «функции-модули» и схемы «модули-данные» проектировщик приступает к решению довольно трудоемкой задачи — написанию спецификаций модулей . Именно это спецификация позволит программистам и компоновщикам построить реальную систему с использованием базы данных .
При написании спецификаций следует исходить из того, что человек, который будет писать код, умеет это делать. Поэтому из спецификаций нужно по возможности исключить все указания по тому, как нужно, с вашей точки зрения, писать код. Это следует из того практического соображения, что никто не может создать правильный код без его тестирования. Поскольку проектировщик базы данных , как правило, сам не собирается писать код, то ему в спецификации не следует диктовать структуру реального кода.
Алгоритмы, даже очень сложные, следует формулировать в общем виде. Нужно стараться избегать формальных языков описания алгоритмов.
Также не следует вставлять в спецификации модулей команды SQL . В процессе тестирования администратор базы данных может изменить разработанную проектировщиком базы данных физическую модель базы данных , и, следовательно, команды могут измениться.
ТОП-9 советов как написать техническое задание? (ТЗ или техзадание за 9 шагов)
Следует избегать лишних инструкций в спецификациях. Например, не нужно объяснять программистам, что они должны выйти из цикла при исключительных ситуациях.
Спецификация модуля должна обязательно включать следующее:
- Условное название модуля.
- Функции, выполнение которых обеспечивает данный модуль.
- Список таблиц и колонок, к которым производится доступ.
- Для каждой колонки — способ использования колонки, а именно, запрашиваются ли, вставляются, удаляются ли, обновляются ли данные указанных колонок.
- Список колонок, которые используются в предикатах поиска.
- Конкретное описание того, что модуль должен делать.
Пример. Приведем типовую спецификацию модуля для предоставления пользователю доступа к приложению базы данных .
Наименование модуля: Страница для входа в приложение (LogIn).
Цель: идентификация пользователя и предоставление доступа к приложению базы данных .
Источник: intuit.ru
Написание технических заданий, требований и спецификаций
Самым грубым образом можно разделить документы на два уровня:
- Высокоуровневые, которых достаточно для понимания конечного результата.
- Детальные, которые полностью описывают, что и как должно быть сделано.
Вторые не всегда нужны, если в проекте работают опытные разработчики, находящиеся в бизнес-контексте (внутренняя команда разработки).
Вторые обязательны, если Вы работаете с внешним подрядчиком или фиксируете стоимость проекта. А это обычное дело, если Вы закупаете услуги по конкурсной процедуре.
Разбираясь глубже, можно было бы выделить массу видов спецификаций, но есть сложности не только с именованием как таковым, а что во что входит. Например, варианты использования и другие UML-диаграммы это могут быть отдельные документы, а могут включаться в ТЗ. Причём, иногда как отдельные части, а иногда внутри других разделов. Тоже самое происходит с текстовыми частями.
Как писать требования так, чтобы команда хотела их читать / Александр Войтехович / ISsoft
Некоторые поставщики, помимо исходного ТЗ, настаивают на собственном ТЗ и на различных видах исполнительной документации. Это всё порождает многообразие того, как комплект технической документации может быть составлен. Тут, на практике, стандарта не получается.
Можно разделить всё документы, используемые в процессе разработки, на:
- Протоколы встреч и согласований
- Документы бизнес-требований
- Документы архитектурного решения
- Документы обоснований
- Функциональные требования и технические задания
- Прочие технические спецификации
Технические задания помимо функциональных требований включают, разумеется, нефункциональные (к быстродействию, способности обеспечить заданную нагрузку, технологические и т.п.), а также концептуальные части.
Аналитики из крупных банков рассказывали мне, что у них есть три уровня документов:
- Документы бизнес-требований (они их называют BRD — Business Requirements Document).
- Архитектурный документ.
- Спецификации на разработку (они их называют SRD — Software Requirements Document).
P.S. 2020 г. В МТС ИТ, где я работаю, архитектурный документ называется «Проект решения». Качество решения держится на единстве контекста в головах аналитиков и архитекторов.
Формат простого технического задания
Если Вы планируете разработку бизнес-приложения с веб-интерфейсом, хотите уложить все требования в один документ ТЗ и ищите формат, который позволит не забыть о важных вещах, могу предложить такой вариант:
- Термины и определения
- Введение
- Общие требования
3.1. Среда выполнения
3.2. Серверная часть
3.3. Браузерная часть
3.4. Журналирование и телеметрия - Контроль доступа пользователей и аудит
4.1. Аутентификация и авторизация
4.2. Права доступа и роли
4.3. Аудит - Пользовательский интерфейс
5.1. Концепция
5.2. Разделы и экранные формы
5.2.x. [Название раздела]
5.2.x. . - Модель предметной области
6.x. [Название объекта]
6.x. . - Периодические задания
7.x. [Название джоба]
7.x. . - Отчёты
8.x. [Название отчёта]
8.x. . - Интеграция и API
9.1. Авторизация при взаимодействиях система-система
9.2. Сценарии взаимодействий
9.3. Предоставляемые API
9.4. Вызываемые API
Однако, имейте ввиду, что в зависимости от ситуации (микросервисный бэкенд или монолитный, SPA или MVC, сценарии внешних взаимодействий и ваш текущий ИТ ландшафт, есть ли отдельная стадия проектирования UI и какой уровень описания требований нужен для неё) некоторые части ТЗ должны получить сильный фокус внимания, а некоторые можно удалить. Шаблон — это только напоминалка.
Опубликовано: 03 ноября, 2018 г.
analysis software documentation
Источник: larionov.pro
Пишем спецификации. Часть 1. Инструменты — начинаем с простого
Чтобы было легче найти нужную спецификацию, надо для них завести централизованное место хранения. Создадим на сервере папку ПРОЕКТЫ с подпапками по числу проектов. Сюда и будем складывать наши документы.
Чуть позже стало понятно, что нам нужны перекрестные ссылки из одного документа на другой. Благо в Ворд-е есть относительно удобный механизм для этого. Можно делать ссылки и внутри документа, и между документами. Со временем стали появляться документы – порталы, состоящие в основном из ссылок на другие документы.
Иногда (точнее, довольно часто) надо вставить в спецификацию какой-нибудь эскиз интерфейса, или скажем UML-диаграмму. Их мы рисуем в Визио, а потом вставляем в спецификацию. Вопрос – где хранить сами визиевские файлы? Давайте придумаем хитрые правила – для хранения связанных файлов будем создавать папку с именем, как у документа, и в нее класть дополнительные материалы.
- За полгода работы над одним из наших проектов было порождено порядка тридцати полновесных спецификаций. Их писали аналитик, ведущий разработчик, и некоторые рядовые разработчики.
- Нам потребовалось:
- программы из пакета MS Office, по числу пишуших спецификации.
- общедоступная папка на сервере для хранения документов.
- Затруднена совместная работа. Если кто-то открыл спецификацию, больше никто в это время ее изменять не может.
- Нет истории изменений. Сложно понять, что изменилось в спецификации с момента твоего последнего чтения. Даже с помощью продвинутых средств Ворда – рецензирования, можно отслеживать только одну итерацию правки документа. Но и при этом документ становится нечитаемым из за подчеркиваний-перечеркиваний и линий-примечаний.
- Затруднен поиск. Сложно найти нужную спецификацию, и в ней – нужную часть. Необходимо помнить, хотя бы приблизительно, как называется документ, и потом пытаться найти его среди пятидесяти его товарищей. Да, казалось бы, в windows есть поиск по файлам. Но нужно сделать кучу шаманских действий, чтобы он начал искать по офисным документам. А потом повторить это на всех тридцати компьютерах разработчиков.
- спецификация
- спецификации
- разработка
- управление проектами
Источник: habr.com