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

«Нас этому не учили!»

Не учат документированию в вузах или учат «между прочим». Умение составлять документацию – важнейший фактор качественной и профессиональной работы программиста. Заказчик никогда не станет вникать в особенности самой качественной и самой нужной ему программы – он будет читать документацию. Советская школа программирования этому учила хорошо: к небольшой программе в несколько сот команд полагались многостраничные документы-руководства (оператора, программиста, пользователя), «Список используемых терминов и сокращений». Эти «бюрократические излишества» теперь не используются. В лучшем случаю, составляется их неэквивалентная замена – документ «Техническое задание» (ТЗ).

Но сейчас программы уже не «пишут» (как произведение искусства), а составляют – по модульному технологичному принципу. Появилась специальность и потребность — технический писатель, копирайтер или человек, умеющий писать программную документацию. Документацию, которая избавит от излишних вопросов и претензий.

Как начать?

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

Для начала следует ознакомиться с ГОСТР, ЕСПД (Единой системой программной документации). В оригинале, без интерпретаторов, «цитаторов».

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

Положения Международного стандарта ISO/IEC и др. носят пока совещательно-рекомендательный характер: они, согласно ФЗ «О стандартизации», становятся обязательны лишь при выполнении международных контрактов по разработке (поставке) ПО.

Что отразить?

Каждый документ имеет:

• наименование документа (и область применения, основание для разработки)
• список используемых сокращений и специальных терминов;
• краткое введение (цель, назначение, актуальность, необходимость, требуемые условия, функционал и т.п.), безо всяких общих «газетных выражений» – передовицы «не из рассматриваемого жанра»;
• основную часть – описание предмета исследований, использованных новых, адаптированных или известных методов, показателей эффективности, проведенных испытаний и исследований;
• заключение – что сделано или должно быть сделано, каковые его отличия от аналогов, как можно развивать и т.п.

Документ оформляется по стандарту А4 и (или) А3, с нумерацией листов (страниц) над текстом.

Как отразить?

Все необходимые изменения и дополнения по ходу выполнения работ приводятся в Дополнении к Документу, согласовываются и утверждаются, как и сам Документ.

В советские времена использовалась схема разработки: ТЗ – Эскизный проект (детали входа-выхода, общее описание модели, метода, алгоритма, программы, плана испытаний) – Технический проект (детализация на уровне, достаточном для программирования) – Рабочий проект (кодирование, тестирование, документирование) – Сопровождение (процесс поиска, исправления скрытых ошибок или «багов» по-современному).

Сейчас чаще используется схема: ТЗ – Программирование и отладка – «Минимальное документирование» – Передача Заказчику.

Показатели качества

Тем не менее, показателями качества и профессионализма при разработке программ являются (кроме всего «обыденного», например, времени, трудозатрат и др.) – на стадии:

• ТЗ – определение критериев эффективности и качества программы, структуры «входа-выхода», методов исследования и проектирования, применение разработанных ранее программ, выяснение и классификация требований к программно-техническому обеспечению и вычислительной среде (особенно, выбор языка программирования и ОС), регламентация разработки;
• программирование и отладка – детализация состава и структуры «входа-выхода», метода и алгоритма, среды программирования, структуры программы и конфигурации необходимых средств;
• документирование – разработка программной документации по утвержденным стандартам и правилам ГОСТР;
• передача Заказчику – передача по акту программы и документации к ней, определение (если в ТЗ их нет) условий сопровождения программы и документации, обучения персонала, консалтинга.

Текст передаваемой программы рассчитан на программиста среднего уровня или на уровень ниже, но никак не на «суперпрограммиста». Главные критерии документированности – удобочитаемость (комментированность), структурированность, полнота, наглядность, содержательность, а также наличие атрибутов программы (наименование, разработчик, дата разработки, версия, последняя модификация, используемый режим работы, совместимость и переносимость, контактные данные).

0

Поделиться

• 0 
•  
• 0