Компания
  • Давайте знакомиться!
  • Наша команда
  • Партнеры
  • Вакансии
Услуги
  • Разработка сайтов
    • Сайты на 1С Битрикс
    • Landing Pages
    • Адаптивные сайты
    • Интернет-магазины
  • Продвижение сайтов
    • Продвижение сайта в ТОП 10
  • Реклама
  • Поддержка и развитие сайтов
    • Увеличение конверсии сайта
    • Стоимость разовой поддержки сайта
  • Брендинг и айдентика
  • Мобильные сайты
  • Приложения для сайтов
    • Калькулятор натяжных потолков
    • Калькулятор рольставен (рольставней)
    • Калькулятор деревянных окон
    • Калькулятор ПВХ окон онлайн
    • Калькулятор секционных ворот
  • Продвижение сайта в cоц. сетях
Портфолио
Клиенты
Блог
Контакты
Ещё
    Tomatys — Дизайн с усами.
    +7 (499) 112-34-82
    Заказать звонок
    • Разработка
    • Продвижение
    • Реклама
    • Кейсы
    • О компании
      • Давайте знакомиться!
      • Наша команда
      • Партнеры
      • Вакансии
    • Контакты
    Tomatys — Дизайн с усами.
    • Разработка
    • Продвижение
    • Реклама
    • Кейсы
    • О компании
      • Назад
      • О компании
      • Давайте знакомиться!
      • Наша команда
      • Партнеры
      • Вакансии
    • Контакты
    • +7 (499) 112-34-82
    Москва, ул. Горбунова д 2 стр 204, БЦ «Гранд Сетунь Плаза», офис 228
    hello@tomatys.com
    • Facebook
    • Вконтакте
    • Twitter
    • Instagram
    • Telegram

    23 Декабря 2013

    Документация по ГОСТу: зачем это современным веб-разработчикам

    О ГОСТах

    Всякий раз, когда я сажусь писать статью о технической документации, мысли так или иначе крутятся вокруг ГОСТов. Не то чтобы я ярый апологет стандартизации, но все же с ними гораздо проще. Не надо изобретать велосипед, не надо придумывать, что писать в техническом задании, как задокументировать процесс передачи выполненной работы заказчику. Все это уже продумано до нас, можно взять из ГОСТа необходимое и адаптировать к своей ситуации. Тем более, что соблюдение стандартов у нас сейчас, согласно законам, — дело добровольное, да и сами ГОСТы, вопреки сложившимся у некоторых представлениям, — это не строгие догмы, шаг влево, шаг вправо — расстрел, а вполне себе гибкие рекомендации. И нужны они не для того, чтобы ограничивать разработчиков, а чтобы сделать процесс разработки менее трудоемким и более эффективным.

    К сожалению, ГОСТов на разработку именно сайтов и веб-приложений нет. Но мы можем рассматривать сайт как программу и ориентироваться на ГОСТ 19, который описывает программную документацию. Не надо ужасаться длинному перечню документов и их древностью (большинство их них датируются еще 70-ми годами). Я предлагаю пробежаться по этому списку и подумать, какие из них могут быть полезны здесь и сейчас нам, современным веб-разработчикам.

    Виды программных документов

    Открываем ГОСТ 19.101-77 Виды программ и программных документов.

    Согласно ему, для программы можно составить вот такие документы:

    Вид программного документа

    Содержание программного документа

    Спецификация

    Состав программы и документации на нее

    Ведомость держателей подлинников

    Перечень предприятий, на которых хранят подлинники программных документов

    Текст программы

    Запись программы с необходимыми комментариями

    Описание программы

    Сведения о логической структуре и функционировании программы

    Программа и методика испытаний

    Требования, подлежащие проверке при испытании программы, а также порядок и методы их контроля

    Техническое задание

    Назначение и область применения программы, технические, технико-экономические и специальные требования, предъявляемые к программе, необходимые стадии и сроки разработки, виды испытаний

    Пояснительная записка

    Схема алгоритма, общее описание алгоритма и (или) функционирования программы, а также обоснование принятых технических и технико-экономических решений

    Эксплуатационные документы

    Сведения для обеспечения функционирования и эксплуатации программы

     

    Тут надо уточнить, что «эксплуатационные документы» — это не один документ, а целая группа:

    Вид эксплуатационного документа

    Содержание эксплуатационного документа

    Ведомость эксплуатационных документов

    Перечень эксплуатационных документов на программу

    Формуляр

    Основные характеристики программы, комплектность и сведения об эксплуатации программы

    Описание применения

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

    Руководство системного программиста

    Сведения для проверки, обеспечения функционирования и настройки программы на условия конкретного применения

    Руководство программиста

    Сведения для эксплуатации программы

    Руководство оператора

    Сведения для обеспечения процедуры общения оператора с вычислительной системой в процессе выполнения программы

    Описание языка

    Описание синтаксиса и семантики языка

    Руководство по техническому обслуживанию

    Сведения для применения тестовых и диагностических программ при обслуживании технических средств

     

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

    На самом деле, у другого человека может получиться немного другой результат — это зависит от специфики работы каждой студии, у меня же список сократился до такого:

    • Текст программы
    • Описание программы
    • Программа и методика испытаний
    • Техническое задание
    • Руководство оператора

    Каждый из этих документов описан своим ГОСТом. Заглянем в них и посмотрим, что там можно почерпнуть полезного.

    Текст программы

    См. ГОСТ 19.401-78 Текст программы. Требования к содержанию и оформлению.

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

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

    Описание программы

    См. ГОСТ 19.402-78 Описание программы.

    Суть этого ГОСТа в том, что нам необходимо представлять себе логику работы программы, ее структуру, условия, при которых она должна работать, какие технические средства ей необходимы. Какие из этих сведений актуальны, если речь идет о сайте или веб-приложении — зависит от конкретного случая. Например, если вы разрабатываете сайт на стандартной CMS, нелишне будет составить список установленных модулей и плагинов. Или если веб-приложение получает данные из других программ, стоит один раз потратить время и записать, каким образом они взаимодействуют.

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

    Программа и методика испытаний

    См. ГОСТ 19.301-79 Программа и методика испытаний. Требования к содержанию и оформлению.

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

    С этим ГОСТом все более-менее понятно, наверное, это один из немногих стандартов, в полезности которых не нужно никого убеждать. Сайт в любом случае тестируют, сами ли разработчики или заказчики, и если у нас будет бумажка, на которой будет написано, что, как и в каком порядке нужно делать, всем будет только проще.

    Результаты испытаний записываются в протоколе. Как правило, протокол — это бланк, в котором требуется лишь отметить, удачно ли прошла каждая операция и каков был ее результат.

    Техническое задание

    См. ГОСТ 19.201-78 Техническое задание, требования к содержанию и оформлению.

    Техническое задание — это, наверное, самый важный из всех программных документов, и даже если у вас совсем нет сил и ресурсов для ведения документации, от ТЗ отказываться я категорически не советую. Отдельно его описывать тут не буду, потому что про него уже была целая статья: «Техническое задание на сайт — для чайников».

    Руководство оператора

    См. ГОСТ 19.505-79 Руководство оператора. Требования к содержанию и оформлению.

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

    Несмотря на то, что интерфейс административной части сайта гораздо интуитивнее и понятнее, чем какая-нибудь система управления бортовой аппаратурой ракеты, руководство администратора сайта все равно необходимо. И в том или ином виде такие руководства существуют. У популярных и распространенных CMS есть сайты, на которых выкладывают официальную документацию, публикуют вопросы и ответы, текстовые и видеоуроки. В каких-то случаях можно ограничиться системой контекстной помощи или всплывающими подсказками.

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

    Поддержание документации в актуальном состоянии

    Допустим, мы напряглись и задокументировали все этапы и аспекты разработки и эксплуатации сайта. Но ведь после запуска он не остается навсегда в неизменном виде. Могут всплыть какие-то ошибки, заказчик может попросить дописать какой-то модуль, в конце концов, может обновиться версия CMS. Да, как ни прискорбно, все эти изменения должны отражаться и в программной документации. И об этом тоже есть ГОСТ: ГОСТ 19.603-78 Общие правила внесения изменений.

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

    1. Любое устранение ошибок в программе или в документе, каждая модификация, новый модуль, изменение процедуры должны где-то фиксироваться — в руководстве пользователя, в виде комментария в коде или любым другим удобным способом.
    2. При этом необходимо поддерживать целостность исходных документов, не допускать разнородности стиля, нарушения логики изложения; другими словами, отредактированные документы должны быть такими же ясными и целостными, как и исходные.
    3. Изменения необходимо отражать во всех документах, к которым они имеют отношение. Если в ТЗ вносится поправка относительно способа загрузки изображений, то аналогичная поправка должна быть, как минимум, и в руководстве пользователя.
    4. Исходя из вышесказанного становится понятно, что документацией должен заниматься один человек. Иначе при всем желании никакой целостности не получится.

    Вернуться ко всем статьям


    Назад к спискуСледующий
    Tomatys — Дизайн с усами.
    Мы занимаемся разработкой сайтов для России и зарубежных рынков с 2011 года. Понимание потребностей онлайн-бизнеса, опыт взаимодействия с тысячами клиентов, высокая квалификация персонала, собственные «ноу-хау» и хороший объём заказов позволяют Томатус предлагать услуги высокого качества по удивительно низким и «вкусным» ценам.

    © 2011–2025
    Политика конфиденциальности

    Компания
    • О «Томатус»
    • Процесс
    • Кейсы
    • Наша команда
    • Вакансии
    • Блог
    • Контакты
    Брендинг
    • Логотипы
    • Фирменный стиль
    Разработка
    • Корпоративные сайты
    • Интернет-магазины
    • Сайты на 1С Битрикс
    • Адаптивные сайты
    Продвижение
    • Оптимизация сайта
    • Аудит эффективности
    • Продвижение в ТОП
    • Продвижение в регионах
    • Контекстная реклама
    Поддержка и развитие
    • Техническая поддержка
    • Комплексная поддержка
    • Разовые работы
    +7 (499) 112-34-82
    Оставить заявку