Инструкция о том как правильно написать описание программы

в Москве и области

в Москве и области

  • Главная » soft » Как написать описание программы?

    Как написать описание программы?

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

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

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

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

    Как начать?

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

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

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

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

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

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

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

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

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

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

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

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

     

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

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

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

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

NAN
0,0 rating
+ 0
2