Как правильно составить техническую документацию

Пишем техническую документацию: руководство для непрофессионала

Осенью 2016 года нам с коллегой поручили улучшить документацию и контент в моей бывшей компании. Мы потратили год на все виды документации: справочник по API, руководства, учебные пособия, сообщения в блогах. До этого я 5 лет писала доки, но официально не обучалась этому. Но и неопытной меня нельзя назвать: кроме документирования API для проектов и стартапа, я ещё преподавала Python Flask на семинарах во время учёбы на последних курсах в университете. Но сейчас выпала возможность сосредоточиться только на любимом деле: помогать специалистам всех уровней через техническую документацию.

В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.

Как люди на самом деле читают документацию?

«Нация содрогается от большого фрагмента слитного текста», фото The Onion

Знаете это чувство, как на картинке? Так бывает. Может и не физически, но, скорее всего, люди содрогаются умственно. Меня постоянно мучала мысль, что люди не будут читать мои тексты, если я не оформлю их легко усваиваемым способом. Чёрт возьми, такое может произойти даже с этой статьёй.

В исследовании направления взгляда Neilson Norman Group в 2006 году 232 пользователя просмотрели тысячи веб-страниц. Оказалось, что пользователи обычно смотрят на страницы по F-шаблону:

1. «Сначала читают в горизонтальном направлении, как правило, в верхней части области с контентом. Это верхний элемент фигуры F».
2. «Затем немного перемещаются вниз по странице — и совершают второе горизонтальное движение, которое обычно охватывает более короткую область, чем предыдущее. Этот дополнительный элемент образует средний элемент фигуры F».
3. «Наконец, пользователи сканируют левую сторону контента по вертикали. Иногда это медленное и систематическое сканирование, которое отображается в виде сплошной полосы на теплокарте. Иногда движение более быстрое, образующее пятна на теплокарте. Это последний вертикальный элемент в фигуре F».

Теплокарты Nielsen Norman Group

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

Важно отметить, что F-шаблон мешает пользователям, но хорошее позиционирование контента помогает предотвратить F-сканирование.

Каковы конкретные последствия для документации?

• В первых двух абзацах следует указать самую важную информацию
• Критически важны первые 3−5 слов
• Заголовки, абзацы и маркированные списки с информативными словами
• Изменения шрифта (размер, ссылки, выделения жирным и т. д.) могут быть необходимы, чтобы удержать внимание читателя

Так как структурировать контент на странице?

• Предотвратите сканирование: убедитесь в выделении информации, которая нужна читателю
• Одна мысль на абзац. Если их несколько, разбейте абзац
• Пользователи пропускают всё, что похоже на баннеры, поэтому будьте осторожны с иллюстрациями
• Не расширяйте слишком сильно колонку с текстом: оптимально 65−90 символов

Некоторые из этих советов я узнала из лекции Кевина Берка «Как писать документацию для пользователей, которые её не читают». Кевин поддерживал документацию Twilio с 2011 по 2014 годы.

Кроме того, у абзацев есть своя специфика. Подобно слитному тексту The Onion, когда вы читаете много абзацев, можно пропустить суть. Тогда зачем использовать их так часто? Давайте проведём эксперимент из документации Keen IO:

Быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил: в названии должно быть не более 64 знаков. Оно должно содержать только символы ASCII. Оно не может быть значением null.

Теперь быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил:

• В названии должно быть не более 64 знаков
• Оно должно содержать только символы ASCII
• Оно не может быть значением null

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

Позже мы подробнее обсудим вёрстку документации и навигацию по ней.

Примеры кода

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

Контекст в примере кода важен для успеха разработчика. Разработчики любят быстро копировать и вставлять. Вот пример с Keen IO API:

var client = new Keen({
  projectId: "your_project_id",
  writeKey: "your_write_key"
});

var ticketPurchase = {
  price: 50.00,
  user: {
    id: "020939382",
    age: 28
  },
  artist: {
    id: "19039",
    name: "Tycho"
  }
}

client.addEvent("ticket_purchases", ticketPurchase);

Разработчик быстро копирует и вставляет этот код. И…

Во-первых, как они вообще запускают файл? Вероятно, как node file_name.js, но этого нет в коде. Можно было бы указать в комментарии вверху.

Хорошо, они запустили его и… ReferenceError: Keen is not defined. Клиент Keen не инициировался, в верхней части нет оператора import или require, и он работает только после установки библиотеки npm.

Пользователь всё починил и запустил ещё раз… Угадайте?! Ещё одна ошибка! your_project_id и your_write_key отсутствуют.

Всё это можно было бы сделать более очевидным.

Вот пример из документации Twilio, которая предоставляет хороший контекст для конечного пользователя:

Скриншот из документации библиотеки Twilio Node Helper

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

Копипаст багов

Поскольку у нас в документации много примеров кода, успешный копипаст — довольно важное свойство. Вот два примера того, где это не соблюдается:

# Скопируйте и вставьте следующую команду
$ gem install rails

Кажется довольно безобидным, верно? Подумайте ещё раз, что происходит, когда вы копируете и вставляете это в командную строку? Вы, скорее всего, получите:

bash: command not found: $

Распространённая ошибка. Либо вы хотите, чтобы команда выглядела как в командной строке, либо вы случайно её скопируете. Я бы рекомендовала отказаться от $. Ещё можно найти способ запретить копипаст этого символа, чтобы ошибка не раздражала пользователей.

Более свежий пример: вы проверяли, насколько легко выделить код, который пользователь хочет скопировать?

Келси Хайтауэр изо всех сил пытался скопировать образец кода из StackOverflow на презентации Google Cloud Next.

«Хорошие программисты копируют, великие программисты вставляют»

Он сделал это намеренно? Мы никогда этого не узнаем. Тем не менее, это иллюстрация, как программисты пытаются выделить большие блоки текста на некоторых сайтах документации. Убедитесь, что пользовательский интерфейс сайта позволяет легко копировать большие блоки. Можно даже разбить эти блоки, чтобы объяснить фрагменты по отдельности. Так они станут доступнее для копирования и понимания.

«Вот и всё!»

«Вот и всё!» Фраза кажется довольно безобидной вне контекста, но представьте, как воспринимаются определённые слова вроде «легко», «просто», «тривиально» и «несложно», когда у вас проблемы — не здорово! Когда человек застрял, пытаясь заставить API работать, такая фраза подвергает сомнению его интеллект и заставляет задать вопрос: «Значит, я глупый?» Это деморализует.

Чрезмерное упрощение

Упрощение встречается повсеместно. Оно наиболее распространено среди новичков в написании документации. Зачастую авторы документации — одновременно и разработчики системы, поэтому некоторые вещи им кажутся «лёгкими». Но ведь они разработали эту функцию, написали для неё код, проверили много, много раз, а потом написали документацию. Когда вы делаете что-то десятки раз, то ясное дело, что это будет «легко» для вас. Но как насчёт того, кто никогда раньше не видел UI или функцию?

Сопереживание

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

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

• Попросите менее опытных участников проекта честно прокомментировать документацию
• Поощряйте менее опытных участников проекта вносить свой вклад или указывать на пункты документации, которые они не понимают
• Создайте окружение, где поощряются вопросы, в том числе такие, какие могут показаться «очевидными» для опытных участников проекта — это поможет заметить «слепые зоны»
• В процессах код-ревью и CI используйте линтеры, чтобы гарантировать эмпатию и дружественность языка для всех пользователей
• Наконец, попросите прокомментировать документацию реальных пользователей, покажите им текст и спросите, всё ли понятно

Сообщения об ошибках как вид документации

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

Кейт на сайте Write The Docs рассказывает много полезного о написании сообщений об ошибках. Многое я узнала во время прошлой работы над сообщениями об ошибках API, а также будучи на другой стороне баррикад, получая сообщения об ошибках других API в качестве разработчика.

Кейт говорит, что хорошие сообщения об ошибках построены на трёх принципах:

• Скромность
• Гуманность
• Полезность

Скромность

Сразу нужно извиниться, даже если это не ваша вина. Это я практикую также в службе поддержки.

Пример:

Извините, не удалось подключиться к ___. Пожалуйста, проверьте сетевые настройки, подключитесь к доступной сети и повторите попытку.

Гуманность

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

Пример (ошибка кода состояния 401 у Twilio):

{ 
    “code”: 20003,
    “detail”: “Your AccountSid or AuthToken was incorrect.”,
    “message”: “Authenticate”,
    “more_info”: “https://www.twilio.com/docs/errors/20003",
    “status”: 401
}

Полезность

Если вы запомните что-то из этих советов, запомните о полезности. Поделитесь с пользователем информацией, как устранить проблему.

Пример:

Извините, изображение, которое вы пытались загрузить, слишком большое. Попробуйте снова с изображения меньше, чем 4000px по высоте и 4000px по ширине.

Как писать сообщения об ошибках

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

Плохой пример:

Нажмите кнопку «назад», чтобы вернуться на предыдущую страницу.

Хороший пример:

Чтобы вернуться на предыдущую страницу, используйте кнопку «назад».

Сообщения об ошибках в документации

Я считаю очень полезным, когда общие сообщения об ошибках API упоминаются в документации. Так автор документации может разъяснить сообщение об ошибке, не увеличивая документацию, в то же время помогая пользователю понять, почему возникает ошибка.

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

В случае ошибки 20003 (ошибка кода состояния 401, упомянутая ранее), есть много возможных причин, которые чётко изложены в каталоге.

Источник: https://www.twilio.com/docs/api/errors

Stripe делает нечто подобное с детальным описанием различных кодов ошибок.

Источник: https://www.twilio.com/docs/api/errors

Вы даже можете найти свои сообщения об ошибках в вопросах StackOverflow. Ответьте на них скромно, по-человечески и с пользой. Из-за SEO пользователи часто попадают с вашими сообщениями об ошибках на StackOverflow, а не в реальную документацию.

Подсказка: если кто-то не ответил скромно, по-человечески и с пользой, то с достаточной «репутацией» можно редактировать ответы StackOverflow.

Выбор слов

У многих слов есть устоявшиеся ментальные модели. Например, такие слова, как «библиотеки», SDK, «обёртки» и «клиенты» уже перегружены и проходят мимо внимания читателя.

В своей лекции «Даже для этой лекции трудно подобрать название» на Write The Docs Рути Бендор говорит, почему выбор правильных слов может быть таким трудным.

Мы часто плохо выбираем слова, хотя при написании текста делаем это постоянно. Как и многие названия SDK, каждое слово вызывает у читателя широкий спектр чувств, идей и определений. Вы можете не понимать этого — и часто мы делаем неправильные предположения.

В такой ситуации как никогда справедлива известная поговорка: «Есть только две трудные задачи в области информатики: инвалидация кеша и придумывание названий». Цитату часто приписывают Филу Карлтону, но сегодня ходит много вариантов этой поговорки. Иногда в конце добавляют «… и ошибка на единицу». Рути считает это демонстрацией, что программное обеспечение в наши дни во многом основано на чужом коде или работе.

Почему же сохраняются плохие названия объектов (или документация)?

Как и с чрезмерным упрощением, мы часто не понимаем, что название плохое. Это то, что Рути называет сбоем эмпатии. Это как сказать, что проблема неудачных слов меня не касается, поэтому её не существует.

Подсказка для США: во избежание случайного расизма используйте слова «запрещённый список» и «разрешённый список» вместо «чёрный» и «белый».
(Источники: Андре Штальц и rails/rails/issues/33677)

Мне это ещё напоминает то, что Рути называет ошибкой мышления новичка. Это как сказать «Мне это совершенно ясно. Не понимаю, как кто-то не может этого понять».

Наконец, Рути упоминает ошибку локализации. Например, слово Bing по-китайски означает «больной».

Согласно исследованию GitHub Open Source Survey за 2017 год:

Почти 25% разработчиков читают и пишут по-английски не «очень хорошо». При общении в проекте используйте понятный и доступный язык для людей из неанглоязычных стран.

Вы это учитываете, когда используете американизмы и идиомы в документации? Многие из них могут быть непонятны для пользователей.

Подсказка: я твёрдо верю, что один из величайших «трюков» для решения этих проблем — разнообразие команды, работающей над документацией.

Есть ещё случаи, когда мы признаём ошибку, но не можем или не хотим её исправлять, потому что мы…

• Привязаны к ней
• Не находим времени
• Не видим важности
• У нас нет агентства, чтобы её исправить

Вы можете сказать или услышать: «Но это моё детище!», «Кто убрал мою конфетку?» «Если мы переименуем, всё сломается», «Не верю, что изменение этого названия повлияет на что-то важное».

Нельзя бояться рефакторинга и переписывания, когда речь идёт о документации. Как же её улучшить, если не соглашаться с тем, что изначально сделан не лучший выбор?

Как правильно подобрать слова?

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

В конце концов, всё неизбежно сводится к субъективной оценке. Однако есть несколько принципов, которые стоит учесть. Рути говорит, что плохие названия — это те, что могут:

• смутить
• огорчить
• ввести в заблуждение
• запутать
• оскорбить

С другой стороны, хорошие названия:

• способствуют внезапному прояснению («вот оно что!»)
• вводят в контекст
• объясняют
• освещают
• оказывают поддержку

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

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

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

Техническую документацию разделяют на несколько видов:

• конструкторская документация
• эксплуатационная документация
• ремонтная документация
• технологическая документация
• документы, определяющие технологический цикл изделия
• документы, дающие информацию, необходимую для организации производства и ремонта изделия

Технической документацией также может называться технические условия, технический паспорт, техническое руководство или техническая литература.

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

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

В производстве продукции существуют следующие виды технической документации – спецификация, паспорт качества, технические условия (ТУ), которые необходимо зарегистрировать в надзорных органах

Опытные эксперты Российского Сертификационного Центра  осуществляют разработку технической документации строго в соответствии с требованиями действующих нормативных документов: Технических регламентов Таможенного Союза, ГОСТ 2 «Единая система конструкторской документации», Стандартов международной организации по стандартизации (ISO), Внутренних стандартов клиента

Техническая документация делиться на несколько видов:

Разработка технических условий

Технические условия на пищевую продукцию

Регистрация технических условий

Разработка технологической инструкции

Расчет энергетической ценности

Паспорт на продукцию

Паспорт безопасности продукции

Регистрация паспорта безопасности

Руководство по эксплуатации

Разработка макета этикетки согласно требованиям ТР ТС

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

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

С 1 июля 2020 года действуют новые требования к оформлению текстовой документации. Цель нового свода правил — стандартизировать форму заполнения конструкторской документации. Структура и состав текстов в сфере строительства, машино- и приборостроения должны подчиняться единым нормам.

Два нововведения предусмотрены приказом Федерального агентства по техническому регулированию и метрологии № 175-ст от 29.04.2019.

• ГОСТ 2.105-95 утрачивает силу в качестве национального стандарта, но сохраняет действие в качестве межгосударственного;
• ГОСТ Р 2.105-2019 признают национальным.

Обратите внимание и на ряд других ГОСТов, принятых в данной сфере:

• ГОСТ Р 2.106-2019 «Единая система конструкторской документации. Текстовые документы», утверждён приказом Росстандарта от 29.04.2019 № 176-ст;
• ГОСТ Р 2.601-2019 «Единая система конструкторской документации. Эксплуатационные документы», утверждён приказом Росстандарта от 29.04.2019 № 177-ст;
• ГОСТ Р 2.711-2019 «Единая система конструкторской документации. Схема деления изделия на составные части», утверждён приказом Росстандарта от 29.04.2019 № 179-ст;
• ГОСТ Р 2.610-2019 «Единая система конструкторской документации. Правила выполнения эксплуатационных документов», утверждён приказом Росстандарта от 29.04.2019 № 178-ст.

Напомним, требования единой системы конструкторской документации (ЕСКД) в РФ считаются добровольными. И если вы выполняете заказ, можно руководствоваться стандартами, выставленными заказчиком. Если документация оформляется для российского рынка, стоит пользоваться правилами оформления из национального свода.

Продолжить работу по ГОСТ 2.105-95 следует, если вы готовите бумаги для партнеров из ЕАЭС. Когда документами пользуются компании и из России, и из других стран, укажите наименование стандарта, который был использован при их подготовке.

Как оформлять документацию: 4 способа

Документы можно подготовить как в электронном, так и в рукописном виде. Для каждого варианта есть свои ГОСТы.

1. Машинописным способом в соответствии с ГОСТ 13.1.002-2003. Межгосударственный стандарт. Репрография. Микрография. Документы для микрофильмирования. Общие требования и нормы (введен в действие Постановлением Госстандарта России от 26.02.2004 № 63-ст).
2. Рукописным методом, используя положения ГОСТ 2.304-81. Межгосударственный стандарт. Единая система конструкторской документации. Шрифты чертежные (утверждён Постановлением Госстандарта СССР от 28.03.1981 № 1562).
3. Применяя ЭВМ, согласно ГОСТ 2.004-88. Межгосударственный стандарт. Единая система конструкторской документации. Общие требования к выполнению конструкторских и технологических документов на печатающих и графических устройствах вывода ЭВМ (утверждён Постановлением Госстандарта СССР от 28.11.1988 № 3843).
4. На электронных носителях информации.

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

Техническое оформление документов: общие требования

Правила ГОСТ к оформлению тестовых документов отличаются. Всё зависит от того, кто утверждал стандарт (Таблица 1).

Таблица 1. Разница и сходство редакций ГОСТ.

Межгосударственный стандарт ГОСТ 2.105-95	Национальный стандарт ГОСТ Р 2.105-2019
Высота символов — не менее 2,5 мм.	Шрифт Times New Roman или Arial размером 14 для основного текста и размером 12 для приложений, примечаний, сносок и примеров; допускается использование шрифта размером 13 и 11 для основного текста и размером 12 и 10 для приложений, примечаний, сносок и примеров соответственно.
Расстояние между боковыми линиями формы и текстом должно составлять минимум 3 мм.
Абзац начинается с красной строки, минимальный отступ — 15–17 мм.	Абзацы начинается с отступа, равного 12,5–17 мм.
От нижней и верхней границ следует отступать не менее 10 мм.
Интервал между строками — не менее 8 мм.	Текст оформляют с использованием полуторного межстрочного интервала; допускается использование двойного межстрочного интервала.
Расстояние между заголовком и текстом при выполнении документа машинописным способом равно 3, 4 интервалам, при выполнении рукописным способом — 15 мм; расстояние между заголовками раздела и подраздела — 2 интервала, при выполнении рукописным способом — 8 мм.	Расстояние между заголовком и текстом, между заголовками раздела и подраздела — не менее 4 высот шрифта, которым набран основной текст. Расстояние между строками заголовков подразделов и пунктов принимают таким же, как в тексте; при выполнении машинописным способом интервал равен 3 или 4 интервалам, при выполнении рукописным способом — не менее 15 мм.

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

Нумерацию документов ЕСКД позволяет сделать как сквозной, так и отдельной для каждого раздела.

Чего делать нельзя: 9 запретов

В требованиях к текстовым документам содержится ряд запретов. Например, требования единой системы конструкторской документации (ЕСКД 2020) года запрещают:

1. Указывать индексы стандартов без обозначения присвоенного им регистрационного номера.
2. Писать математические знаки без числового сопровождения.
3. Ставить знак минус для обозначения отрицательных чисел.
4. Перечеркивать круг в качестве обозначения диаметра.

В самом тексте недопустимо применять:

1. Сокращения слов, кроме установленных правилами русской орфографии, соответствующими государственными стандартами, а также в данном документе.
2. Обороты разговорной речи, техницизмы, профессионализмы.
3. Для одного и того же понятия различные научно-технические термины, близкие по смыслу (синонимы), иностранные слова и термины при наличии равнозначных слов и терминов в русском языке.
4. Произвольные словообразования.

К физическим величинам тоже есть требования:

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

Отклонение от обязательных требований не допускается, в соответствии с действующими правилами следует оформлять любой элемент текста.

В данной статье я попытался подробно рассмотреть проблему разработки Технических заданий. Тема стара, как и проблема. Но она до сих пор часто решается «как получится». Как сказал Генри Шоу «Мелочи тревожат нас больше всего: легче увернуться от слона, чем от мухи».

О чем эта статья?

Меня часто спрашивают: «Как правильно разработать техническое задание для автоматизированной системы?».  Аналогичная тема постоянно обсуждается на различных форумах. Этот вопрос настолько широкий, что ответить в двух словах никак нельзя. Поэтому я решил написать большую статью на данную тему.  В процессе работы над статьей я понял, что уложить все в одной статье не выйдет, т.к. получится под 50 страниц и решил разбить ее на 2 части:  

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

• Вторая часть «Разработка Технического задания. Как формулировать требования?» будет полностью посвящена выявлению и формулировке требований к информационной системе.

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

• Коммерческая организация решила внедрить у себя автоматизированную систему. Она не имеет собственной  IT-службы и решили поступить так: Заинтересованное лицо должно разработать Техническое задание и отдать его на разработку сторонней организации;

• Коммерческая организация решила внедрить у себя автоматизированную систему. Она имеет собственную  IT-службу. Решили поступить так:  разработать Техническое задание, затем согласовать его между IT-службой и заинтересованными лицами, и реализовать собственными силами;

• Госструктура решила затеять IT-проект. Тут все настолько мутно, куча формальностей, откатов, распилов и пр. Я не буду рассматривать такой вариант в данной статье.

• IT-компания занимается услугами по разработке и/или внедрению автоматизированных систем. Это наиболее сложный случай, ведь приходится работать в самых различных условиях:

  • Клиент имеет своих специалистов со своими взглядами, и они предъявляют конкретные требования к Техническому заданию;

  • Техническое задание разрабатывается для собственных разработчиков (клиенту все равно);

  • Техническое задание разрабатывается для передачи подрядчику (т.е. группе программистов, находящихся за штатом компании, или отдельному специалисту);

  • Между компаний и клиентом возникает непонимание в вопросе полученного результата, и компания вновь и вновь задается вопросом: «Как надо разрабатывать Техническое задание?». Возможно, последний случай кажется парадоксом, но это правда.

  • Возможны и другие, реже встречающиеся варианты;

Думаю, сейчас у читателя должны возникнуть вопросы:

• А почему нельзя разрабатывать Техническое задание всегда одинаково?

• Существуют ли какие-то стандарты, методики, рекомендации? Где их взять?

• Кто должен разрабатывать Техническое задание? Должен ли этот человек обладать какими-то специальными знаниями?

• Как понять, хорошо составлено Техническое задание или нет?

• За чей счет должно оно разрабатываться, да и нужно ли оно вообще?

Этот список может быть бесконечным. Говорю так уверенно от того, что уже 15 лет в профессиональной разработке программного обеспечения, а вопрос о Технических заданиях всплывает в любом коллективе разработчиков, с кем приходиться работать. Причины тому разные. Поднимая тему разработки Технического задания, я прекрасно отдаю себе отчет в том, что не смогу изложить ее на 100% для всех интересующихся темой. Но, попробую, как говорится «разложить все по полочкам». Те, кто уже знаком с моими статьями знают, что я не пользуюсь «копи-пастом» труда других людей, не перепечатываю чужие книги, не цитирую многостраничные стандарты и прочие документы, которые Вы и сами сможете найти в интернете, выдавая их за свои гениальные мысли.  Достаточно набрать в поисковике «Как разработать Техническое задание» и Вы сможете прочитать много интересного, но, к сожалению, многократно повторяющегося. Как правило, те, кто любит умничать на форумах (попробуйте все-таки поискать!), сами никогда не делали толкового Технического задания, и непрерывно цитируют рекомендации ГОСТов по данному вопросу. А тем, кто действительно серьезно занимается вопросом, обычно некогда сидеть на форумах.  Про ГОСТЫ, кстати, мы тоже поговорим. В разные годы своей работы мне приходилось видеть множество вариантов технической документации, составленной как отдельными специалистами, так и именитыми командами и консалтинговыми компаниями. Иногда еще я занимаюсь такой деятельностью: выделяю себе время и занимаюсь поиском информации на интересующую тему по необычным источникам (такой небольшой разведкой). В результате приходилось видеть документацию и по таким монстрам, как ГазПром, РЖД и много других интересных компаний. Конечно же, я соблюдаю политику конфиденциальности, несмотря на то, что эти документы попадают ко мне из общедоступных источников или безответственности консультантов (разбрасывают информацию по интернету). Поэтому сразу говорю: конфиденциальной информацией, которая принадлежит другим компаниям не делюсь, независимо от источников возникновения (профессиональная этика).

 Как ни странно, проблемы у всех одинаковые! У всех бывают как успешные документы (и проекты), так и совсем бестолковые  (исключение, пожалуй, составляют Технические задания, разработанные еще во времена, когда не было персональных компьютеров, но там были совсем другие условия).  Почему так получается? Именно потому, что цели у проектов бывают разные, как и пользователи этих документов. И, конечно, компетенции непосредственных специалистов не на последнем месте.  В этих двух статьях я попытаюсь  поделиться своим личным  опытом, накопленном  за многие годы. Конечно, получится в сжатом виде, т.к. вопрос достоин целой книги (кстати, идея, а может написать?)…  

Что такое техническое задание?

Первое, что мы сейчас сделаем, так это разберемся с тем, что за зверь такой, «Техническое задание».

Да, действительно существуют ГОСТы и стандарты, в которых предприняты попытки регламентировать эту часть деятельности (разработки программного обеспечения). Когда-то все эти ГОСТы были актуальны и активно применялись.  Сейчас существуют разные мнения по поводу актуальности данных документов. Одни утверждают, что ГОСТы были разработаны очень дальновидными людьми и до сих пор актуальны. Другие говорят, что они безнадежно устарели.  Возможно, кто-то сейчас подумал, что правда где-то по серединеJ. Я бы ответил словами Гете: «Говорят, что между двумя противоположными мнениями находится истина. Ни в коем случае! Между ними лежит проблема». Так вот, между этими мнениями истины нет. Потому как ГОСТы не раскрывают практических проблем современной разработки, а те, кто их критикует, альтернативы (конкретной и системной) не предлагают.

Заметим, что  в ГОСТе явно не дано даже определения, сказано лишь: «ТЗ на АС является основным документом, определяющим требования и порядок создания (развития или модернизации — далее создания) автоматизированной системы, в соответствии с которым проводится разработка АС и ее приемка при вводе в действие».

Если кому-то интересно, о каких ГОСТах я говорю, то вот они:

• ГОСТ 2.114-95 Единая система конструкторской документации. Технические условия;

• ГОСТ 19.201-78 Единая система программной документации. Техническое задание. Требования к содержанию и оформлению;

• ГОСТ 34.602-89 Информационная технология. Комплекс стандартов на автоматизированные системы. Техническое задание на создание автоматизированной системы.

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

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

И так, как следует из определения, основное назначение Технического задания — сформулировать требования к разрабатываемому объекту, в нашем случае к автоматизированной системе.

Именно основное, но единственное. Настало время взяться за главное: разложить все «по полочкам», как и обещал.

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

• Требования в функциональности;

• Требования к безопасности и правам доступа;

• Требования к квалификации персонала;

• …. И т.д. Вы можете  прочитаете о них в упомянутом ГОСТе (а ниже я их тоже рассмотрю немного подробнее).

Думаю, для Вас очевидно, что ключевым фактором успешного Технического задания являются именно хорошо сформулированные требования к функциональности. Именно этим требованиям посвящено большинство работ и методик, о которых я говорил. Требования к функциональности – это 90% сложности работ по разработке Технического задания. Все остальное зачастую является «камуфляжем», который надет на эти требования.  Если требования сформулированы плохо, то какой красивый камуфляж на них не натягивай, успешного проекта не выйдет. Да, формально все требования будут соблюдены (по ГОСТу J), ТЗ разработано, утверждено и подписано, деньги за него получены. И что? А дальше начнется самое интересное: что делать-то? Если это проект на ГосЗаказе, то проблем нет – там бюджет такой, что ни в какой карман не влезет, в процессе реализации (если она будет) все и будет выясняться. Именно таким образом и пилится большинство бюджетов проектов на ГосЗаказах (накалякали «ТЗ», слили десяток миллионов, а проект делать не стали. Все формальности соблюдены, виновных нет, новое авто возле дома.  Красота!).  Но ведь мы говорим о коммерческих организациях, где деньги считают, да и результат  нужен другой. Поэтому давайте разбираться с главным, как разрабатывать полезные и работающие Технические задания.

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

1. Требование должно быть понятным;

2. Требование должно быть конкретным;

3. Требование должно быть тестируемым;

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

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

• на каком языке (в смысле сложности понимания) должно быть написано техническое задание? 

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

• А что такое техническое  проектирование, о котором, кстати, сказано и в ГОСТах, и как оно связано с Техническим заданием?

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

Так вот:

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

Технический проект – это документ, который предназначен для технической реализации требований, сформулированных в Техническом задании. Как раз в этом документе описываются структуры данных, триггеры и хранимые процедуры, алгоритмы и прочие штуки, которые потребуютсятехническим специалистам. Заказчику в это вникать вовсе не обязательно (ему и термины такие могут быть непонятны). Технический проект делает Архитектор системы (вот совмещение этой роли с программистом вполне нормально).  А точнее группа специалистов во главе с архитектором. Чем больше проект, тем и больше людей работает над Техническим заданием.

Что мы имеем на практике? Забавно наблюдать, когда директору приносят на согласование Техническое задание, которое изобилует технической терминологией, описанием типов данных и их значений, структуры базы данных и пр. Он, конечно, пытается вникнуть, раз надо утверждать, пытаясь найти между строк знакомые слова и не потерять цепочку бизнес-требований.  Что, знакомая ситуация?  И чем это заканчивается? Как правило, такое ТЗ утверждается, затем реализуется, а в 80% случаев потом совсем не соответствует факту выполненных работ, т.к. много чего решили изменить, переделать, неправильно поняли, не так думали и т.д. и т.п. А потом начинается сериал про сдачу работ. «А вот тут не так как нам надо», а «это у нас работать не будет», «это слишком сложно», «это неудобно» и т.д. Знакомо?!! Вот и мне знакомо, пришлось набить шишек в свое время.

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

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

Управленческий учет: с нуля до настройки в 1С, Excel и Google-таблицах

Уметь настраивать и вести управленку — значит быть полезным для руководителей. Научитесь понимать, откуда приходят и куда уходят деньги компании на курсе повышения квалификации от «Клерка».

А нужно ли вообще техническое задание? А Технический проект?

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

А что же с Техническим проектом? Данный документ весьма полезный и не утратил свою актуальность. Более того, часто без него просто не обойтись. Особенно, если речь идет о передаче работ по разработке на сторону, т.е. по принципу аутсорсинга. Если этого не сделать, есть риск узнать много нового о том, как должна выглядеть система, которую Вы задумалиJ.  Должен ли с ним знакомиться  Заказчик? Если хочет, почему нет, но настаивать  и утверждать данный документ нет никакой необходимости, он будет только сдерживать и  мешать работать. Спроектировать систему до мелочей практически невозможно. В этом случае придется непрерывно вносить изменения в Технический проект, что занимает немало времени. А если организация сильно забюрократизирована, то вообще все нервы там оставите. Как раз о сокращении такого рода проектирования и идет речь в современных методологиях быстрой разработки, о которых я упоминал выше. Кстати, все они базируются на классическом XP (экстремальном программировании)- подходе, которому уже порядка 20 лет. Так что сделайте качественное Техническое задание, понятно Заказчику, а Технический проект используйте как внутренний документ, для взаимоотношений между архитектором системы  и программистами.

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

Продолжим исследование вопроса: «Какие требования включать в Техническое задание?»

Формулирование требований к информационной системе. Структура Технического задания

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

Как и любую деятельность, формулирование требований можно (и нужно) разделить на этапы. Всему свое время. Это тяжелый интеллектуальный труд. И, если относится к нему с недостаточным вниманием, то результат будет соответствующий.  По экспертным оценкам, стоимость затрат на разработку Технического задания может составлять 30-50%. Я придерживаюсь такого же мнения. Хотя 50 – пожалуй, перебор. Ведь Техническое задание – это еще не последний документ, который должен быть разработан. Ведь еще должно быть и техническое проектирование. Такой разброс обусловлен различными платформами автоматизации, подходами и технологиями, применяемыми проектными командами при разработке. Например, если речь идет о разработке на классическом языке типа С++, то без детального технического проектирования тут не обойтись. Если речь идет о внедрении системы на платформе 1С, то тут с проектированием ситуация несколько иная, как мы видели выше (хотя, при разработке системы «с нуля», она проектируется по классической схеме).

Несмотря на то, что формулировка требований является основной частью Технического задания, а некоторых случая она становиться единственным разделом ТЗ, следует обратить внимание на то, что это важный документ, и оформлять его следует соответственно. С чего начать? В первую очередь начать надо с содержания. Составьте содержание, а затем начните его разворачивать. Лично я делаю так: сначала набрасываю содержание, описываю цели, всю вводную информацию, а затем принимаюсь за основную часть – формулировку требований. Почему не наоборот? Не знаю, мне так удобнее. Во-первых, это гораздо меньшая часть времени (по сравнению с требованиями), во-вторых, пока описываешь всю вводную информацию, настраиваешься на главное. Ну это кому как нравится. Со временем у Вас выработается свой шаблон Технического задания. Для начала рекомендую в качестве содержания взять именно тот, что описан в ГОСТ. Для содержания он подходит отлично!  Затем берем и начинаем описывать каждый раздел, не забывая про рекомендации следования трем свойствам: понятности, конкретности и тестируемости. Почему я на этом так настаиваю?  Об этом в следующем разделе. А сейчас предлагаю все-такт пройтись по тем пунктам ТЗ, которые рекомендуются в ГОСТе.

И так, ГОСТ рекомендует следующие разделы:

1. общие сведения;

2. назначение и цели создания (развития) системы;

3. характеристика объектов автоматизации;

4. требования к системе;

5. состав и содержание работ по созданию системы;

6. порядок контроля и приемки системы;

7. требования к составу и содержанию работ по подготовке объекта автоматизации к вводу системы в действие;

8. требования к документированию;

9. источники разработки.

Итого, 9 разделов, каждый из которых тоже делится на подразделы. Разберем их по-порядку. Для удобства представлю все в виде таблицы по каждому пункту.

Раздел 1. общие сведения.

Раздел 2. назначение и цели создания (развития) системы.

Раздел 3. Характеристика объектов автоматизации.

Раздел 4. Требования к системе

Раздел 5. Состав и содержание работ по созданию системы

Раздел 6. Порядок контроля и приемки системы

Раздел 7. Требования к составу и содержанию работ по подготовке объекта автоматизации к вводу системы в действие

Раздел 8. Требования к документированию

Раздел 9. Источники разработки

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

Но вот без главного: функциональных требований ни одно грамотно  Техническое задание не обходится.  Хочу  заметить, что в практике такие Технические задания встречаются, и еще как! Есть деятели, которые сумеют развести воды по всем разделам, опишут общие требования общими словами, и документ получается весьма увесистый, и слов в нем умных много, и даже Заказчику может понравится (т.е. он его утвердит). Но вот работать по нему может не получиться, т.е. практической пользы от него мало. В большинстве случаев такие документы рождаются, когда надо получить много денег  именно под Техническое задание, а сделать его надо быстро и не погружаясь в детали. А особенно, если известно, что дальше дело не пойдет, или его будут делать совсем другие люди. В общем, просто для освоения бюджета, особенно государственного.

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

Почему требования должны быть понятными, конкретными и тестируемыми.

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

Надеюсь, идея понятна. Если будут конкретные вопросы, пишите, попробую помочь.

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

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

• Следует стараться не использовать длинных предложений;

• Если какое-то требование Вам кажется слишком общим, его необходимо детализировать до более мелких, но конкретных требований;

• Используйте больше схем, графиков, таблиц, рисунков – так информацию воспринимается гораздо легче;

• Следует избегать таких слов: «эффективный», «адекватный», «простой», «понятный», «быстрый», «гибкий», «улучшенный», «оптимальный», «прозрачный», «устойчивый», «достаточный», «дружественный», «легкий» и др.  Перечень можно продолжать, но, мне кажется идея понятна (попробуйте его продолжить самостоятельно).

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

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