КомпанияУслугиОбучениеСервисы

A Ghost of the GOST

Версия для печати

Михаил Острогорский, 2008

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

Время от времени на форум «Философта» приходит обескураженный технический писатель или инженер, чтобы задать один извечный вопрос. Поводом к нему всякий раз служит что-то свое, но суть остается неизменной: «Как применить положения госта к реальному материалу, с которым мне приходится иметь дело?». Вопрос сопровождается объяснениями, почему гост на данный конкретный случай не налезает.

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

Тут бы и поставить точку, но не получается. Во-первых, требование использовать определенный комплекс стандартов часто приходит извне, то есть возможности выбора нам не предоставляют. Во-вторых, авторы гостов наверно были (а ныне здравствующие остаются) очень мудры, но мы-то не такие. Госты базируются на своеобразной системе обобщающих понятий, что делает их применимыми почти к любой ситуации. Однако эта широта оплачена таким уровнем отвлеченности, что иной раз приходишь в замешательство. Допустим, о некотором разделе документа сказано, что он должен содержать «описание функционирования системы и ее частей». А что это означает по существу? Функционирование системы можно описывать с разных точек зрения и с разной подробностью. В зависимости от трактовки этого требования у нас может получиться страница текста, а может роман в стихах с картинками. И таких формулировок в стандартах немало.

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

Чем руководствоваться? Невозможно же всякий раз идти на поклон к толкователям.

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

Кроме того, если мы говорим о КСАС, то имейте в виду, что п. 1.2 документа РД 50-34.698-90 гласит: «Допускается включать в документы дополнительные разделы и сведения, объединять и исключать разделы». Этот пункт развязывает вам руки и позволяет многие вещи делать по собственному усмотрению.

Таким образом, мы приходим к следующим правилам.

A) Не создавайте документов, которыми заведомо никто не будет пользоваться. Если же начальники или заказчики от вас этого требуют, постарайтесь их отговорить. Речь в данном случае, конечно, идет об осмысленной деятельности, а не о проформе. Для проформы нам могут приказать написать все что угодно. Но если мы работаем на корзину для бумаг, то и особенно вникать в содержание ни к чему, достаточно простого формального соответствия тому, что буквально написано в гостах.

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

C) Если вы не знаете, в какой документ поместить те или иные сведения, подумайте, кому они нужны. Поместите их в один из документов, предназначенных для того, кто в них заинтересован. Как уже было сказано, вы имеете право так поступить.

Следование этим правилам предполагает, что вы хорошо представляете себе:

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

К сожалению, ни в КСАС, ни в ЕСПД об этом явно почти ничего не сказано. В отношении наиболее распространенных эксплуатационных документов мы сейчас восполним этот пробел.

Документ	                Комплекс стандартов         Аудитория

Спецификация	                        ЕСПД                    ИТ-менеджеры
                                                                Сисадмины

Формуляр                                КСАС и ЕСПД             ИТ-менеджеры
                                                                Сисадмины

Общее описание системы                  КСАС                    ИТ-менеджеры

Инструкция по эксплуатации КТС          КСАС                    Сисадмины

Руководство системного программиста     ЕСПД                    Сисадмины

Руководство оператора                   ЕСПД                    Пользователи

Руководство пользователя                КСАС                    Пользователи

Технологическая инструкция              КСАС                    Пользователи

Теперь вы сами можете толковать гост. Вернемся к примеру, которого мы уже касались выше. Вот выдержка из требований к документу Общее описание системы согласно РД 50-34.698-90.

==============================================
2.11.3. В разделе "Описание системы" указывают: 
1) структуру системы и назначение ее частей; 
2) сведения об АС в целом и ее частях, необходимые 
   для обеспечения эксплуатации системы; 
3) описание функционирования системы и ее частей. 
===============================================

Какие именно сведения о частях АС надо приводить? В каком смысле следует понимать описание функционирования системы, надо ли описывать заложенные в нее алгоритмы или имеется в виду что-то другое?

Мы уже говорили, что требования госта следует рассматривать применительно к определенному предмету документирования. В качестве примера возьмем тот же форум «Философта» и будем трактовать его как автоматизированную систему.

Из каких частей состоит эта система? В госте нет строгого определения части системы. Поэтому мы примем самостоятельное решение считать ее частями функциональные подсистемы. Их три: «Участник», «Администратор» и «Баннеры».

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

«Участник»

  • участие в работе форума возможно только для пользователя, заявка которого утверждена администратором форума;
  • для полноценной работы участника необходимо, чтобы у него в веб-браузере была включена поддержка JavaScript.

«Администратор»

  • должен быть назначен хотя бы один администратор форума, учетная запись которого входит в группу Superusers;
  • администратор обязан ежедневно рассматривать заявки на участие, подаваемые пользователями.

«Баннеры»

  • подсистема позволяет отобразить один баннер 468x60 в верхней части и два баннера 100x100 в нижней части страницы форума;
  • должен быть назначен администратор баннеров, обладающий правами доступа на сервер по протоколу FTP;
  • для отображения баннеров необходимо, чтобы в веб-браузере у участника была включена поддержка JavaScript.

О работе системы в целом ИТ-менеджеру необходимо знать следующее.

  • программное обеспечение форума размещено и функционирует на сервере провайдера;
  • для работы форума используется домен третьего уровня forum.philosoft.ru;
  • резервное копирование данных и ПО форума выполняется провайдером ежедневно.

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

По какому принципу выбраны именно эти сведения? Да по очень простому: если ИТ-менеджер не будет этого знать, то эксплуатацию форума он не организует, а если будет, то организует. Именно они критически важны, что следует не из формальных соображений, а из содержательных. Ведь составители госта ведь ничего не знали ни о «Философте», ни о его форуме.

© «Философт», 2008–2017

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG