Лекция № 17. Составление программной документации

Содержание лекции: виды программных документов; пояснительная записка; руководство пользователя.

Цель лекции: ознакомиться с видами программных документов и основными правилами оформления программной документации.

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

К программным относят документы, содержащие сведения, необходи­мые для разработки, сопровождения и эксплуатации программного обеспе­чения. Документирование программного обеспечения осуществляется в со­ответствии с Единой системой программной документации (ГОСТ 19.ХХХ). Так ГОСТ 19.101-77 устанавливает виды программных документов для ПО различных типов. К основным про­граммным документам по этому стандарту относятся: спецификация, ведомость держателей подлинников, текст программы, описание программы, ведомость эксплуатационных документов, формуляр, описание применения, руководство системного программиста, руководство программиста, руководство оператора, описание языка, руководство по техническому обслуживанию, программа и методика испытаний, пояснительная записка. Допускается объединять отдельные виды эксплуатационных докумен­тов. Необходимость объединения указывает­ся в техническом задании, а имя берут у одного из объединяемых документов. При оформлении текстовых и графических материалов, входящих в программную документацию также следует придерживаться действующих стандартов. Рассмотрим подробнее некоторые из перечисленных документов.

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

Следующим по важности документом является программа и методика испытаний (ПМИ). Структурно она подобна ТЗ – практически для каждого пункта ТЗ в ПМИ говорится, как этот пункт будет проверяться. Способы проверки могут быть самыми разными – от пропуска специального теста до изучения исходных текстов программы, но они должны быть предусмотрены заранее, а не придумываться в момент испытаний. Новички приступают к составлению ПМИ непосредственно перед завершением работ, а опытные руководители составляют и согласовывают с заказчиками одновременно с ТЗ. Хорошо составленная ПМИ является гарантией успешной сдачи работ.

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

Руководство оператора (пользователя) – это основной документ, описывающий, как пользоваться системой [16]. В хорошем руководстве сначала описывается идея системы, основные функции и как ими пользоваться, а уже потом идет описание всех клавиш и меню.

Руководство программиста - это самый объемный документ, описывающий внутреннюю организацию программы. Обычно этот документ идет в паре с документом " текст программы " – одностраничным документом с оглавлением дискеты или CD. Руководство программиста дает заказчику возможность дописать новые фрагменты программы или переделать старые. В современной литературе этот документ называется SDK (Software Development Kit). Продукт, снабженный SDK, может стоить на порядок дороже, чем такой же продукт без него. Сейчас не принято продавать исходные тексты программ – проблемы с интеллектуальной собственностью, даже при наличии SDK трудно "влезть" в чужую программу – как говорится, себе дороже. Поэтому большое распространение получили API (Application Program Interface). Программа передается только в виде DLL (библиотека двоичных кодов), но известно, как обратиться к каждой функции из других программ, т.е. известно имя точки входа, количество, типы и значения параметров. Наличие множества API, конечно, хуже, чем наличие исходных текстов (например, нельзя переделать что-то в середине функции), зато много проще в использовании. С другой стороны, все большую популярность приобретает FSF (Free Software Foundation). Основателем этого движения был Ричард Столман [4], который забил тревогу по поводу попыток крупных фирм запатентовать многие основные алгоритмы и программы: "Дойдет до того, что они запатентуют понятия "цикл" и "подпрограмма", что мы будем тогда делать?" FSF представляет собой собрание программ в исходных текстах; любой программист может свободно использовать их в своих целях, но все добавления и улучшения, которые он сделал, тоже следует положить в FSF. Таким образом, FSF представляет собой одно из самых больших доступных хранилищ программ.

Дополнительную информацию по теме можно получить в [1, 4, 16].