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

Вопрос документировать требования или нет - не стоит. Скорее есть вопрос в форме. По форме есть постоянные споры в нашей команде.

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

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

Есть преимущества такого подхода:
- документирование требований в таком виде не требует больших затрат;
- до программиста доходит уже проектное решение достаточно сухое и более менее точное;
- отдается предпочтение "теплому" общению над "холодным"

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

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

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

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

Что могут сказать гуру по требованиям и управлениями ими в этой связи?

Примите свой стандарт, если нет внешних ограничений - например, требований заказчика соблюдать тот или иной стандарт.

Мы именно так и поступали.

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

Были попытки реализовать заимствованные стандарты и разработки - но пока не прижились. Имхо, особенность определенного данного сообщества людей. Это может быть и не плохо, но боюсь не масштабируемо, не наследуемо Хотя возможно я слишком драматизирую

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

Что могут сказать гуру по требованиям и управлениями ими в этой связи?

А не-гурам можно?

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

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

Эти документы служат базой для тестирования.

Кроме этих документов, разрозненные требования фиксируются в нашей базе (которую с некоторой натяжкой можно назвать википодобной).

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

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

Спасибо гурам и не-гурам

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

Причем тут дело даже не в форме представления знаний, а в контроле за изменениями и актуальностью этих знаний.

Как делается сейчас (или по крайней мере к этому стремимся)

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

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

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

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

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

Как мы работаем. Есть у нас testlink. В него мы загоняем постановку и часто сами ее разделяем на требования (как понимаем сами). По требованию стараемся написать хотя бы один тестовый случай. Далее уже в правлении работами создаем работу на создание тестовой процедуре на тестовом стенде.

А у вас как?

Так может вам просто система управления тестами нужна, а не шаблон документирования?

Идочка, так она у нас есть, толку-то. Или Вы нечто иное под этим понимаете? Внутри наших тестов мы вполне наладили обмен и обновление, но ведь проблема в ином - внешние события

Система все перечисленное делать не позволяет? Не без участия человека, разумеется

Не совсем понял вопроса? Пока есть только система управления работами, естественно подписаться на все возможные изменения можно, но это будет такой поток событий - захлебнешься.

На вики есть грубое приближение к формату постановок. Но сами постановки оформляются пока в виде word файла и размещаются на общем доступе и ... не соответствуют предложеному формату

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

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

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

Решил не смешивать с предыдущим постом.

Тему я начал вот по какой занятной причине.

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

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

Если вдуматься внимательно в разговор, получается, что следование ТЗ или другим официальным стандартам и практикам - идет в разрез здравому смыслу, изначально непонятно и не доступно простому читателю (но вероятно доступно человеку подготовленному). Т.е. язык ТЗ по сути некий птичий язык, которому следует обучаться, и который есть показатель профпригодности?

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

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

Могу ли я надеяться на помощь столь уважаемого сообщества аналитиков?

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

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

Ограничения: модуль разрабатывается в среде проектирования. которую и будут документировать. структура класса выгружается в виде XML со стандартной схемой СПП

Ну как-то так. Интересно как это может выглядеть в виде ТЗ 34? Или возможно других стандартах и шаблонах?

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

Марина, давайте обойдемся без оскорблений, даже третьих лиц.

Слишком много технических терминов
Мы же все ходим в магазин, носки покупаем (ну или там - помидоры).
Объясните, какие носки вам нужны - мы расскажем, как их связать или где купить.

Задача поставлена четко, нужно не покупать помидоры или носки, нужно документировать класс и встраивать его в топик проекта.
Справочная система реализуется сторонними инструментами. Согласно этому инструменту: проект - это некий файл, содержащий ту или иную справочную систему, топик - раздел такой справочной системы.
К тому же это задание на разработку по сути внутреннего назначения. Заказчиком выступает человек (группа людей) отвечающих за создание руководства программиста по использованию инструментов разработки.
Разработчиком выступает сотрудник компании.

Пока мне непонятно, зачем разрабатывать модуль, который позволял бы документировать класс и встраивать его (кого его? - модуль? класс? описание класса?) в справочную систему.

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

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

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

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

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

Если вдуматься внимательно в разговор, получается, что следование ТЗ или другим официальным стандартам и практикам - идет в разрез здравому смыслу, изначально непонятно и не доступно простому читателю (но вероятно доступно человеку подготовленному). Т.е. язык ТЗ по сути некий птичий язык, которому следует обучаться, и который есть показатель профпригодности?

Складывается впечатление, что все эти люди (кроме программиста-исполнителя) ГОСТ 34 либо внимательно не читали, либо не использовали. Нет там ничего птичьего. Другое дело, что некоторые фразы ГОСТа нельзя понять, не имея опыта в той сфере, на которую эта фраза ссылается. Нужно обратить внимание исполнителя, в первую очередь, на самый главный пункт :

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

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

А во время службы в НИИ ВВС приходилось иметь дело уже с реальными, "боевыми" ТЗ, оформленными по ГОСТу. И там на буковки, конечно, никто уже не смотрел. Зато всегда знали, где и что нужно искать. Но ТЗ задаёт только структуру - грубо говоря, чтобы не пропустить что-нибудь важное.

Я из твоего длинного поста не очень понял проблему. Тебе нужно подготовить документ, обязательно оформленный "по ГОСТу"?

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

Большой юридический словарь.
С каких пор медицинские термины стали неприличными?...

А почему Вы ставите людям диагноз? Вы сертифицированный психиатр?

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

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

А трясти терминами нужно, чтобы произвести впечатление

Да же улыбающаяся физиономия не скрывает грубости этой фразы. В данном случае я ничем не трясу. Тем более терминами.
Я уже

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

Платформа уже существует. Она содержит более 3000 классов. Классы эти не документированы. Струкутур классов можно получать в некотором формате - это я уже писал:

В системе предусмотрены возможности получения структуры классов и его составляющих в некотором формате X.

.

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

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

Складывается впечатление, что все эти люди (кроме программиста-исполнителя) ГОСТ 34 либо внимательно не читали, либо не использовали. Нет там ничего птичьего.

Может это связано с тем, что не было особой потребности в этом?

А во время службы в НИИ ВВС приходилось иметь дело уже с реальными, "боевыми" ТЗ, оформленными по ГОСТу. И там на буковки, конечно, никто уже не смотрел. Зато всегда знали, где и что нужно искать. Но ТЗ задаёт только структуру - грубо говоря, чтобы не пропустить что-нибудь важное.

Вообще главные потребители документов по ГОСТ - это военные орагнизации

Я из твоего длинного поста не очень понял проблему. Тебе нужно подготовить документ, обязательно оформленный "по ГОСТу"?

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

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

Серьезно? Если, честно, я поражен.

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

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

Документ был забракован отделом проектирования с резолюцией НЕПОНЯТНО.

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

Серьезно? Если, честно, я поражен.

Совершенно серьёзно.

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

Документ был забракован отделом проектирования с резолюцией НЕПОНЯТНО.

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

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

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

Могу рассказать, как работаю сейчас.

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

В ГОСТах используется своя терминология, во многом советских времён, которой в коммерческих организациях не владеют (АС, ЭВМ, пункты управления, шифр темы, временной регламент и т. п. - для многих сейчас это уже терминологический мусор). А если заказчик этих слов не знает, зачем мне их использовать?

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

2.10. В разделе «Требования к документированию» приводят:
...
2) требования по документированию комплектующих элементов межотраслевого применения в соответствии с требованиями ЕСКД и ЕСПД;

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

На моей памяти, такие ссылки за последние пять лет нужно было приводить раза два. Заказчик был в кризисе, год молчал, у него полностью сменился персонал, а сейчас ожил и решил реанимировать старый проект. Причём начал с тестирования и сразу выкатил претензию. Пришлось искать согласованную версию ТЗ и давать ссылку на утверждённое предыдущим директором требование. Ну и дал бы я ему номер абзаца вместо текста, что это изменило бы? Разве что ссылка была бы красивой, вроде: "RTFM ТЗ пункт 1.2.3.4".


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