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

О ГОСТах

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

К сожалению, ГОСТов на разработку именно сайтов и веб-приложений нет. Но мы можем рассматривать сайт как программу и ориентироваться на ГОСТ 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. Исходя из вышесказанного становится понятно, что документацией должен заниматься один человек. Иначе при всем желании никакой целостности не получится.

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