Внимание! Мы обновляем сайт! Все для технического писателя и разработки технической документации. Внимание! Мы обновляемся!

Комплект программной документации на составную программу (систему)

 obmen_soobsheniyami.png Чат для технических писателей 
 Зарегистрируйтесь
Страницы: 1
RSS
Комплект программной документации на составную программу (систему), Вопрос о том, как корректно сформировать набор документов для сложной программы, имеющей в своем составе несколько модулей, в т.ч. стороннее ПО (ОС)
 
Добрый день!

С недавних пор я занимаюсь разработкой технической документации, начиная от оформления ТЗ и заканчивая комплектом программной документации.

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

Пример: разрабатываемая программа - система управления некоторым оборудованием. В ее состав входит, к примеру:
1) Некоторая сборка ОС (Linux)
2) Компонент 1 (основной)
3) Компонент 2 (выполняет функцию такую-то, взаимодействует с компонентом 1 и 4)
4) Компонент 3 (выполняет еще какую-то функцию, взаимодействует с компонентом 1 и 4)
5) Компонент 4 (загрузочный, взаимодействует со всеми компонентами)

Система функционирует только в совокупности всех компонентов (все они должны присутствовать, включая именно эту сборку ОС).
Компоненты не предназначены для функционирования независимо друг от друга.

Лирическое отступление о стадиях разработки: в сферическом случае в вакууме их должно быть пять (ГОСТ 19.102-77): техзадание, эскизный проект, технический проект, рабочий проект и внедрение. В реальности ТЗ пишется параллельно непосредственной разработке программы, еще не утверждено на момент начала разработки, и в лучшем случае формально процесс разбить можно на три стадии: ТЗ, рабочий проект и внедрение (благо ГОСТ позволяет выкинуть остальные две). Поэтому у меня еще и некоторая каша по поводу того, как разбивать документацию по стадиям. О пояснительной записке у нас речи даже не идет. Получается, документация у нас: на стадии техзадания - само ТЗ по ГОСТ 19.201-78, на стадии рабочего проектирования - некоторый набор документов по ГОСТ 19. 101-77

У меня представляется два варианта рассмотрения такой системы и соответственно два варианта наборов документации.

Вариант 1: рассматривать систему как одну программу. Это самый простой вариант - комплект документов включал бы в себя:
1) ТЗ - оно у нас одно на всю систему, без ЧТЗ (в ТЗ каждый компонент описан как "модуль", т.е. Модуль 1 должен делать то-то, Модуль 2 должен делать то-то, отдельным пунктом - требования к сборке ОС).

2) Описание программы ГОСТ 19.402-78 - описывалась бы вся система целиком, включая все компоненты
3) Описание применения ГОСТ 19.502-78
4) Формуляр ГОСТ 19.501-78
5) Руководство оператора ГОСТ 19.505
6) Руководство системного программиста ГОСТ 19.503
7). Спецификация, в которой перечислены: документы (2) - (6), Компоненты: отсутствуют, Комплексы: отсутствуют или сюда должна вписываться используе6мая сборка ОС?

Вариант2: мне он кажется нагляднее и корректнее - рассматривать систему как программу-комплекс, а ее составные части - как программы-компоненты.
Что у нас тогда получится в наборе документов:
1). ТЗ - то же самое;

Для всей системы в целом (для комплекса)
2). Описание программы
3) Описание применения
4) Формуляр
5) Руководство оператора
6) Руководство системного программиста
7) Спецификация, в которой перечислены: документы (2)-(6), Компоненты: спецификации компонентов 1, 2, 3, 4, Комплексы: сборка ОС (?)

Для компонентов 1...4:
1) Спецификация (в которой перечислены: документы (2) - (6), компоненты: отсутствуют, комплексы: отсутствуют)
2) Описание программы
3) Формуляр
4) Руководство оператора
5) Руководство системного программиста
6) Описание применения


Итак, мои вопросы:
1. Какой из двух вариантов является более верным? Кто должен выбирать степень "разбиения" сложного ПО на компоненты - технический писатель, начальство, заказчик?
2. Что именно пишут в Формуляр в разделе Комплектность? Если моя программа состоит из Prog.exe, settings.config, 123.dat, library.dll, то все эти файлы и перечисляются в данном разделе?
3. Верно ли я понимаю принцип построена набора документации для программного комплекса? (Что набор документов по ЕСПД составляется для самого комплекса в целом, а также для каждого компонента в частности?)
4. Как присваивается код программной документации комплексам и компонентам? (например: А.В.00001 - комплекс, А.В.00002 - Компонент 1, А.В.00003 - компонент 2 и т.д. ?)
5. Как быть с компонентами, которые не применяются самостоятельно? В ГОСТ 19.202-78 написано: спецификация является основным ПД для компонентов, применяемых самостоятельно, и для комплексов. Для компонентов, не имеющих спецификации, основным ПД является "Текст программы". Если в указанной системе все компоненты 1...4 не могут применяться самостоятельно, это значит, что я не имею право выбирать Вариант 2, т.к. несамостоятельные компоненты не могут иметь спецификацию?
6. Как в вариантах 1 и 2 указать использование сборки ОС? Это ПО нами не разрабатывается, но необходимо для работы системы. Сборка ОС указывается в спецификации как "Комплекс"?
Изменено: afilnara - 02.06.2015 14:47:56
 
На все вопросы не отвечу, так, отдельные мысли на тему:

Если это система управления оборудованием, и вы же будете заниматься её внедрением, наверно, 34 ГОСТ будет более уместен, чем 19.

Разбиением систем на компоненты занимается, конечно, не техписатель, а "начальство" - менеджер проекта, системный архитектор и т.д. По большому счету и писать все программную документацию должен не техписатель, его прямая обязанность - пользовательская документация, остальное опционально. Список документов начальство согласовывает с заказчиком где-то на стадии подписания договора, и в этом списке документы перечисляются уже с кодами. Если договор подписан, программисты работают, а списка документов нет, скорее всего, как они будут обозначены - не очень принципиальный вопрос.

Если по 19 госту, мне больше нравится первый вариант - меньше писанины, которую никто не читает. Зачем, например, руководство оператора для каждого компонента? Формуляр - это, кажется что-то из древности, для хранения в архивах. Если программа устанавливается исполнителем на компьютеры заказчика, вполне можно обойтись без него (тем более в 5 экземплярах).


Из ГОСТ 19.402-78 Описание программы:
Цитата

6. В разделе «Описание логической структуры» должны быть указаны:
  • алгоритм программы;
  • используемые методы;
  • структура программы с описанием функций составных частей и связи между ними;
  • связи программы с другими программами.

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

А ещё программы и методики испытаний в списке документов очень не хватает.
 
Спасибо за ответ!

Вы правы насчет программы и методики испытаний, я забыла его упомянуть. Если быть точнее, то пока ТЗ еще не утверждено, и в данный момент этого документа в списке документов нет, но я подозреваю, что его включат, т.к. тестирование системы, конечно, запланировано.

Формуляр у нас присутствует в ТЗ в разделе требующейся документации, поэтому мне бы хотелось, конечно, знать, как его корректно заполнять, включают ли в него полностью все файлы, относящиеся к программе (их ведь будет в конечном итоге не один десяток).

Я также пока не очень хорошо понимаю, где грань между ГОСТ 34 и ГОСТ 19. По ГОСТ 34 определение AC: "Система, состоящая    из персонала и комплекса средств автоматизации его деятельности, реализующая    информационную технологию выполнения установленных функций". Я понимаю, что, например, программы для бухгалтерского учета можно рассматривать как АС, т.к. они заменяют ручное заполнение бумажек/отчетов и т.д. и вписываются в определение. А как быть, если рассматриваемое ПО - некоторая система управления оборудованием, которая собирает данные с оборудования, позволяет конфигурировать какие-то параметры, просматривать эти параметры и логи их значений через некоторые интерфейсы ... считается ли это "автоматизацией деятельности персонала"? Кроме того, лично мы не занимаемся "внедрением" ПО. Мы, грубо говоря, даем диск с некоторыми файлами, которые заказчик будет переносить на флешку, флешку устанавливать на плату, плату ставить в корпус, и дальше оно все будет работать само при подаче питания.
 
Про формуляр ничего не подскажу - никогда писать не приходилось.

Замечание про 34 ГОСТ снимаю. Итог работы по 34 ГОСТу - автоматизированный процесс "под ключ". Т. е. не только написано ПО, но и установлено, настроено, при необходимости закуплено и установлено железо, на котором оно будет работать, протянуты сети, обучен персонал, написаны инструкции для разных ролей работы с системой и т.д. Не обязательно все это делает один исполнитель, но важно, что это должно быть прописано в договоре и ТЗ и выполнено. Если итог работы - диск с кодом, 34 ГОСТ не нужен.
 
Спасибо. Про ГОСТ 34 стало понятно. Меня к тому же запутали ТЗ на предыдущее ПО, которые я получила в качестве образцов. К примеру, ТЗ на ПО, которое включало в себя серверную и клиентскую части, разнесенные территориально, а также подразумевало установку (сервера и клиентов), тестирование, обучение персонала и т.д., было оформлено по ГОСТ 19. По вашему объяснению выходит, что там как раз должен был быть применен ГОСТ 34. :/
Страницы: 1
Читают тему