Документирование в разработке ПО

INTRO


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

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

Итак, для начала отвечу на главный вопрос: для чего всё это нужно.
Есть несколько причин.

1. Документация обеспечивает «общее пространство» проекта. Любой участник в любой момент времени может получить необходимую информацию как по конкретной задаче, так и по общему направлению работы.
2. Команда говорит «на одном языке» — ведь гораздо проще понять человека, сообщающего «об ошибке в функции, описанной в Use Case №12», чем «о стрёмном баге в той фигне, которую Вася месяц назад делал».
3. Документирование позволяет четко разграничить зоны ответственности между участниками проекта.
4. Только тщательно описанные требования могут быть проверены на полноту и непротиворечивость. «Наколенные записки» — прямой и очень быстрый путь к тому, что границы проекта расползутся резвыми тараканами, а функционал, задуманный вначале, не будет монтироваться с возникающими в процессе «хотелками» заказчика.

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

1. Документация не должна быть избыточной и объемной. Мы пишем документы не за-ради приятного процесса постукивания по клавишам, а для того, чтобы их использовать в работе. Избыточное количество текста – раздражает и затрудняет восприятие.
2. Вся схема документирования проекта должна быть взаимоувязанной и логичной. Если в схеме существует документ, который не связан ссылкой с каким бы то ни было другим документом, то его можно безболезненно из схемы исключить.
3. Вся оценка трудозатрат должна производиться только на основании описанных атомарных задач. Сложно оценить разработку «функционала подсистемы ввода данных», гораздо проще оценить задачи «разработка формы ввода данных марсиан» и «разработка фильтра списка марсиан». Чем мельче оцениваемый элемент – тем точнее будет агрегированная оценка.
4. Всегда необходимо формировать списки оповещения заинтересованных участников. Разработчик, узнающий о необходимости доработки за три дня до релиза – это зло и подлейшая подлость, аналитик, втихаря поменявший требования и не уведомивший всех заинтересованных участников о необходимости доработки – последняя свинья, а РП, допустивший такую ситуацию – чума, холера и неприятный человек, который не справляется со своими обязанностями.

Я предлагаю на суд уважаемого сообщества схему документирования, которая кажется мне удобной, логичной и правильной. И – да, это работает.

Итак, какие типы документов используются в схеме.

1. Техническое задание.
2. Частное техническое задание (опционально).
3. Сценарий использования (Use Case).
4. Сценарий тестирования (Test Case).
5. Отчет об ошибке (Bug Report).
6. Руководство пользователя.
7. Руководство администратора (опционально).

На рисунке ниже — схема связи между этими документами.


Как это работает?

ТЗ


Изначально, при обследовании, формируется Большое Техническое задание.
Оно включает в себя:
• словарь терминов предметной области;
• описание предметной области;
• описание ролевой системы;
• описание функциональных требований;
• описание нефункциональных требований.
Описание требований в этом документе фиксируется на «верхнем уровне», то есть мы описываем не конкретные действия, а только необходимые функции. Требования оптимально разбивать на смысловые группы по подсистемам.
Например, мы описываем подсистему «Администрирование» с функциями «Создание карточки пользователя», «Удаление карточки пользователя», «Редактирование карточки пользователя». Это требования верхнего уровня, ниже в ТЗ опускаться смысла нет.

ЧТЗ


В случае, если система большая, разумно сделать Частные технические задания на каждую подсистему.
ЧТЗ должны содержать:
• ссылку на пункт ТЗ;
• максимально подробную информацию по каждой функции;
• список UseCases для функции.
Таким образом реализуется преемственность документов, что позволяет, во-первых, унифицировать их форму, во-вторых – частично реализовать повторное использование, то есть снизить затраты времени на «писанину».
Например, мы формируем ЧТЗ на всё ту же подсистему «Администрирование». Оно будет содержать описание функции: «Создание карточки. Необходимо реализовать следующий функционал: вызов карточки посредством кнопки «Создать», интерфейс карточки, содержащий следующий набор полей, сохранение карточки посредством кнопки «Сохранить», отмену сохранения посредством кнопки «Отмена»».

Use Case


Use Case — суть вариант использования, он описывает все действия, которые пользователь может произвести, и реакцию системы на эти действия.
Каждый Use Case должен быть привязан к пункту ЧТЗ.
Наиболее оптимальным, на мой взгляд, является формат описания, включающий в себя:
• Макет экрана. Макеты можно делать и сложные, «кликабельные», но, по опыту, хватает «проволочной диаграммы», сделанной с помощью Visio или аналогичного инструмента. Если на форме предполагается использование модальных окон, то они тоже должны быть прорисованы, нижеописанные таблицы для них должны дублироваться.
• Диаграмму действий экрана, в графическом виде описывающую алгоритм работы функции.
• Таблицу с описанием полей. В строке таблицы должны располагаться следующие данные: название поля, тип поля, ограничение на ввод данных (логические проверки и т.д.), роли пользователей, которым доступно чтение/редактирование поля. Если поле расчетное – то необходимо указывать формулу для расчета значения.
• Таблицу с описанием действия кнопок экрана. В строке таблицы должны содержаться данные о названии кнопки, описание действия при клике и путях перехода, если щелчок по кнопке предполагает переход на другой экран, роли пользователей, которым доступно действие.
Также возможно небольшое общее описание функционала но, как правило, оно просто не нужно.

Test Case


Test Case, что вполне самоочевидно, должен содержать описание тестовых сценариев.
В идеале, каждый такой документ привязывается к соответствующему Use Case, но бывает так, что логично объединить несколько Use Cases в один Test Case.
Оптимальным вариантом формата описания является таблица, содержащая в одном столбце описание атомарной операции, влекущей ответное действие системы, во втором – описание правильной реакции системы. Описывать, к примеру, процесс ввода текста в текстовое поле не нужно, а вот проверку валидности данных при сохранении (щелчке по кнопке «Сохранить») – обязательно.

Bug Report


Ещё немного побуду кэпом: Bug Report возникает в процессе тестирования системы как реакция тестировщика на ошибку. Каждый документ должен обязательно ссылаться на соответствующий Test Case.
Содержать документ должен:
• скриншот возникшей ошибки;
• описание предшествующих действий. Лучше всего разработать удобный для всех шаблон такого описания – это сильно экономит время разработчикам при воспроизведении бага;
• текстовое описание самой ошибки.

Руководство пользователя/Руководство администратора


Самые занудные в написании, но, тем не менее, жизненно необходимые документы.
По сути, их формирование можно даже автоматизировать, если все Test Cases и Use Cases были написаны с должным старанием и правильно оформлены.
Я не буду подробно на них останавливаться, если вдруг тема заинтересует – расскажу о том, как их составление можно автоматизировать.

Заключение


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

Подробнее
Реклама
Комментарии 42
  • 0
    Большое спасибо за статью. Можете привести пример применения такой схемы к проекту который
    делают уже пару лет, но, при этом, вы никак не можете с ним разобраться, потому что из документов есть одно техническое задание
    ?
    • 0
      Добрый день.
      Рада, что оказалась полезной.

      По сути, схема должна быть такой же, меняется только процесс разработки. Получается некий вариант «reverse engineering».

      По опыту: нужно выделить одного аналитика, который станет «штатным занудой» и задолбает всех вопросами «как это работает и зачем тут эта менюшка». Неблагодарный, на первом этапе, труд, слишком часто нафиг норовят послать :)
      На основании полученных данных он составить «большое ТЗ» и, по необходимости, ЧТЗ.
      Параллельно нужно запустить процесс «потокового документирования», то есть написания Use Cases и Test Cases для новых задач. Тут очень важно, чтобы РП был адекватный и умел настоять на необходимости «описывать каждый чих». Все новые доки должны сразу же подвязываться к ТЗ/ЧТЗ.
      Естественно, обязательно нужно использовать технические средства совместной работы, поддерживающие версионность.
      Постепенно можно довести ситуацию до близкой к идеалу.

      На самом деле, мне кажется, что тут гораздо больше довлеет не «техническая проблема», а чистая психология: команда, которая не привыкла работать по документам, со скрипом перестраивается на другой режим работы. Приходится уговаривать и шантажировать :)
    • 0
      Спасибо за статью. Вопрос: в какой программе вы ведете эту документацию?
      • 0
        Мы пользуемся связкой SVN+Jira.
        • 0
          Для таких документов зело удобно пользовать Confluence с плагинами.
          • 0
            Balsamiq Mockups обязательно посмотрите
        • 0
          У меня есть проблема: есть проект, который в разработке более 3лет и состоит из нескольких подпроектов. Там есть веб сайт, виндовые приложения, базы данных, классы, скрипты, в общем, зоопарк. Документации нет. я сам через пару месяцев с трудом вспоминаю, в каких частях и по какой логике у меня реализован тот или иной функционал. С чего вы мне порекомендуете начать процесс документирования? По моему представлению в документации должна содержаться логика, ссылки на реализующую локику классы, методы, файлы, системы и т.п. алгоритмы, выдимо, тоже должны быть задокументированы…
          • +2
            Начинать всегда проще «сверху».
            Попробуйте просто составить реестр функций, которые выполняются в системе. Функции лучше разбивать на смысловые блоки: что происходит на сайте, что в одном приложении, что в другом, и так далее. Условно это будут Ваши подсистемы. Описание на уровне «в приложении „погода“ пользователь может: посмотреть погоду на сегодня, посмотреть погоду на неделю, настроить автообновление».
            Потом функции можно разобрать на составляющие: «для просмотра погоды на неделю необходимо щелкнуть по кнопке „Неделя“». И уже к этой вот составляющей можно привязать описание алгоритмов, классов, методов и прочих ценных «кишок» системы.

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

            Конечно, труд титанический, но, на выходе, полученный результат сэкономит Вам в дальнейшем очень много времени.
            Если есть необходимость, стучите в личку — могу попробовать помочь.
            • 0
              Спасибо. эксель не годиться, хотелось бы научиться пользоваться чем то более структурирующим. наверное, нужно подробнее почитать документацию к тем инструментам, которые я использую (Visual Studio + TFS)
              • 0
                С TFS доводилось работать, вполне удобный инструмент.
                Удачи Вам :)
            • +1
              Здравствуйте.

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

              Документация для пользователей. Это люди, которые пользуются вашим сайтом и виндовыми приложениями. Здесь сгодится принцип построения документации по принципу описания Use Case'ов. Вы смотрите какие задачи выполняют пользователи и составляете пошаговые инструкции. Пример можно посмотреть здесь: help.yandex.ru/passport/. Инструменты для начала простые — MS Word, LibreOffice Writer и т.п.

              Документация для разработчиков. Есть вы не предоставляете API сторонним разработчика, то документировать свой код можете так, как вам лично будет удобнее. Это могут быть комментарии в коде, файлики readme.txt в подкаталогах проекта и т.д. Хитрую логику может быть полезно описать блок-схемами, картинками со стрелочками и т.д. Можно поднять локальный вики-движок (или использовать Google Sites), это позволит с лёгкостью создавать необходимые документы и расставлять ссылки между ними.

              Получилось сумбурно. Рассказать что-то точнее можно уже глядя на проект и понимая требования к документации.
              • 0
                Спасибо.
                Мне в первую очередь нужна документация для себя и своих коллег — программистов. С точки зрения логической структуры мне близок вариант Redlady, а вот как его удобно реализовать — большой вопрос.
                предположим, у меня будет описан на верхнем уровне функционал какой-то подсистемы. Затем я захочу детальнее расписать все функции. В каждой функции я могу захотеть подробнее описать предметную область, добавить картинки, схемы, ссылки на куски кода в моем приложении, чтобы при чтении всего этого хозяйства я мог легко и быстро понять: зачем этот функционал нужен, в какой предметной области он работает, какие он использует (или требует) внешние данные, как он их обрабатывает, при помощи какого конкретно кода он это делает.
                причем хочется иметь возможность из этой структуры генерировать какие-то «полезные» обзорные отчеты. я вообще сам хотел для себя сделать некоторую систему документирования. чтобы там были сущности (система, функционал, БД, таблица, класс, метод, и т.п.), чтобы при документировании у меня была четкая система ссылок между всеми частями проекта: документацией, кодом, данными, файлами и т.д.
                вот, кстати, практический вопрос: как сделать такую ссылку, которая будет расположена вне visual studio (например, в ворде) при нажатии на которую я попаду на конкретный кусок кода в visual studio. наверное, какой-то add-in должен существовать. Есть же ссылки типа mailto:vasya@pupkin.com, значит, наверное, что-то подобное должно существовать.
              • 0
                Когда я работал над докуменацией большой системы, годами жившей без этого, то просто начал описывать то, с чем я сталкиваюсь сейчас. Т.е. нет как такового проекта «написать документацию», это была просто одна из частей текущей работы. Есть модуль, есть запрос на изменения, документации нет — значит параллельно с постановкой задачи документируем текущее состояние.
                Так оно относительно безболезненно происходит, так как ты все время в нужном контексте. Чем отрываться и пытаться написать документацию ко всему сразу.
                • 0
                  Согласен. так и буду делать, спасибо.
                • 0
                  Самый лучший способ — берете разработчика, который только что поставил новую функцию. Не просто закодил, а функция попала к заказчику и прошла проверку реальными пользователями. Пусть сделает по ней презентацию минут на 15, со сладами, выступлением и ответами на вопросы коллег. Это все запишите на видео.

                  Тоже можно сделать по старым функциям. День подготовки каждого человека, на выходе 5-8 часов видео со всей архитектурой системы и расшаренный опыт на всю команду + прокаченные presentation skills.

                  Не пишите текст, как только суммарный объем перевалит за 30 страниц плотного теста читать это никто не будет.
                • 0
                  Спасибо за любопытную статью!
                  Согласна практически со всем, но хотелось бы дополнить про роль use cases в ЧТЗ. Все-таки, один use case может включать в себя несколько единиц функциональности (features), и хорошо бы их отдельно описывать. Кроме того, кейсы могут ветвиться (либо, если структура нашего документа не допускает ветвления, они могут частично дублировать друг друга). Получается исчерпывающее описание, но зачастую сложное для обобщенного восприятия разработчиками.
                  Я предпочитаю делать список вариантов использования перед формированием ТЗ (естественно, после интервьюирования представителей заказчика), потом делать сам документ с описанием отдельных функций, а там уже, при необходимости, можно ссылаться на документ с вариантами использования. Ну и, как Вы правильно отметили, нет ничего лучше использования user cases для тестирования :)
                  • 0
                    Ваш вариант мне тоже нравится :)
                    Естественно, не существует однозначных рецептов, я описала только один способ. Многое зависит от специфики проекта, команды и личный предпочтений аналитика.
                  • –1
                    Статья очень интересная. Но как Вы пишите требования до определения юскейсов? Сначала ведь надо бы определить хотя бы верхнеуровневый скоуп будущей системы. Т.е. выделяются роли, затем для каждой из них — варианты использования. С этого момента становится понятно, что система должна делать. А затем уже можно детализировать (описывать конкретные сценарии использования для юскейсов, функциональные и нефункциональные требования, бизнес-правила). Требования ведь не «висят в воздухе», а привязываются к конкретным целевым функциям системы (как раз к нашим юскейсам). То же и для макетов интерфейса (кстати кроме платного Balsamiq можно рассмотреть бесплатный Evolus Pencil :) ).
                    • 0
                      Я просто опустила этап сбора требований, потому что это такая отдельная история :)
                      Все требования генерятся на основании описания бизнес-процессов заказчика. То есть собрали информацию, согласовали описание процессов, отсюда и пляшу, на основании процессов выделяю подсистемы и функции, и дальше в лес, к упитанным партизанам.

                      кроме платного Balsamiq можно рассмотреть бесплатный Evolus Pencil

                      Спасибо, обязательно посмотрю.
                    • 0
                      В нашей компании часто приходится браться за крупные (государственные проекты) с сжатыми сроками и постоянной нехваткой рабочих рук. Из имеющихся программистов в проектировании, тестировании и документировании разбираюсь я один (по должности — руководитель отдела). Долго пытался применять подход, предложенный Ларманом в книге «Применение UML и шаблонов проектирования» (к слову, очень советую прочесть), но в связи с хранической нехваткой времени, пришлось выработоть иной подход. Поднял внутрифирменную mediaWiki, заставил всех программистов записать в нее все реализованные проекты (описание, цели, модели классов, базы данных и так далее), сам тоже принял активное участие. Со временем система разрослась еще и в учебное пособие для начинающих. С помощью используемой на фирме СЭД информирую программистов о ходе проекта, ставлю задачи. Для небольшого коллектива, считаю, такой подход наиболее оптимален, не требует особых вложений и легок в освоении. К сожалению тестирование еще не поставил на поток.
                      • 0
                        Коллега, я тоже с госами работаю :)
                        Лармана читала, спасибо. Его методология, как и любая другая, имеет право на жизнь, но использовать её «в чистом виде» можно только на сферических проектах в вакууме.
                        Наши с Вами подходы различаются, в первую очередь, по той причине, что Вы, насколько я поняла, изначально разработчик, а я аналитик :)
                        Это не значит, что один подход лучше другого, они оба могут работать, всё зависит от многих факторов: привычек команды, объёмов и типа проектов, способов постановки задач.

                        Просто любопытство: а гостовую документацию у Вас техпис делает?
                        • 0
                          К счастью ни наш начальник, ни клиенты не знают о существовании ГОСТа, надеюсь и не узнают, если вы понимаете о чем я )
                          • 0
                            О да, я Вам искренне завидую белой завистью :)
                            У меня все в курсе…
                      • 0
                        Это вся документация по проекту или документация, которую пишет бизнес-аналитик? Мне кажется, что документов должно быть больше :) По крайней мере вам нужны нефункциональные требования к системе, которые хорошо бы согласовать и подписать с заказчиком. А также внешние интерфейсы вашей системы, а для серверных приложений схема деплоймента.
                        • 0
                          Это документация, которую пишут аналитики.
                          Нефункциональные требования включаются в ТЗ, я их в описании документа даже отельным буллетом выделила :) Схема деплоймета, как правило, включается туда же отдельным пунктом.
                          Вот для внешних интерфейсов лучше писать самостоятельные доки, этот момент я в тексте упустила. Обещаю исправиться :)
                        • –1
                          Вот у вас описаны цели:
                          1. Документация обеспечивает «общее пространство» проекта.
                          2. Команда говорит «на одном языке».
                          3. Документирование позволяет четко разграничить зоны ответственности между участниками проекта.


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

                          Только тщательно описанные требования могут быть проверены на полноту и непротиворечивость

                          Так не бывает. Математически доказано что не бывает полной и непротиворечивой системы. Кроме того, чем больше текста и чем больше участников, тем меньше вероятность что все участники одинаково поймут все написанное.
                          • 0
                            Только документация в этом не помогает. Помогает трекинг-система, в которой можно описывать связанные UC, задачи, баги и тест-кейсы.

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

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

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

                            • 0
                              По документом я подразумеваю не текстовый файл

                              Точно? У вас указано 7 типов документов, из которых 4 это текстовые файлы. По крайней мере других представлений для ТЗ, ЧТЗ и инструкций в дикой природе я не видел.

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

                              Use Case и Bug Report вообще не являются документированием, тем не менее вы про них пишите.
                              • 0
                                Точно? У вас указано 7 типов документов, из которых 4 это текстовые файлы. По крайней мере других представлений для ТЗ, ЧТЗ и инструкций в дикой природе я не видел.

                                А что мешает оформлять и хранить ТЗ и ЧТЗ в той же jira и делать в них ссылки на варианты использования? Это во-первых. Во-вторых, любой текст, даже оформленный в таблицу и размещённый в трекере, является, по сути, текстовым документом.

                                Use Case и Bug Report вообще не являются документированием, тем не менее вы про них пишите.

                                Почему эти сущности не являются документами?
                                • 0
                                  ТЗ в первую и последнюю очередь пишется для согласования с заказчиком. Если такого нет, то списка Use Case сгруппированного по Epic и Theme более чем достаточно. Для ТЗ и ЧТЗ есть определенный формат описания (текстового), как в России, так и за рубежом. Естественно заказчик будет согласовывать текстовый документ, а не что-то-там в трекере.

                                  Вообще самое понятие проектной документации заключается в том, что документы являются некоторым результатом проекта (артефактами), наряду с некоторым продуктом\изделием\программой. Багрепорты такими артефактами не являются, они никому не нужны за пределами проекта. Use Case из трекера тоже. Тест планы тоже зачастую никакой пользы не несут после того, как ими закончили пользоваться. Это все инструменты управления, как и почта, пересылаемая между сотрудниками. Вы же почту в документацию не записали.
                                  • 0
                                    У меня сложилось ощущение, что Вы оперируете сугубо терминологией ГОСТов.
                                    Я под термином «документирование» подразумеваю весь набор артефактов, которые возникают на всех этапах жизненного цикла проекта.
                                    В тексте вполне осознанно нет упоминаний о целевой аудитории тех или иных документов, акцент сделан на взаимоувязанность элементов системы.
                                    • 0
                                      Исходный код получается тоже является документированием? А email? Или сообщения в чате? Получается что все что делается — документирование. Это как-то расходится с общепринятой терминологией.

                                      Без правильно поставленных целей создания тех или иных арртефактов все остальные аспекты не являются значимыми. Вот объясните кому нужна эта «взаимоувязанность»?
                                      Заказчику? Он глубже ТЗ не полезет. Разработчикам? Они будут работать на уровне UC. Разве что менеджеру, которому необходимо следить чтобы результат соответствовал ТЗ. Но для этого придумали Программу и Методику Испытаний (ПМИ), которая позволяет проверить, что результат соответствует ТЗ. Тогда «взаимоувязка» ТЗ и UC не играет никакой роли.

                                      ГОСТы кстати не лохи придумали. Стоит почаще к содержательной части гостов обращаться. Увы многие смотрят только на оформительскую часть.
                          • +1
                            Вот почитайте мысли очень опытного ПМа и просто грамотного человека на тему документации — gaperton.livejournal.com/60632.html
                            • 0
                              Gaepton, безусловно, имеет право на собственное мнение. Оно, с одной стороны, перекликается с моими мыслями, с другой стороны — является противоположным.
                              Истина, как водится, где-то посередине.
                              Если Вам действительно интересен сравнительный анализ — я готова его сделать и опубликовать. Если же Вы считаете Garepton гуру, а всех прочих дураками, то я не буду пытаться Вас переубедить.
                              • 0
                                В отличие от вас у него очень четко описано какая документация и зачем пишется. А у вас этого нет.
                                Также у вас не написано для кого пишется документация и кто её пишет. Это сводит полезность поста почти к нулю.

                                Может быть в голове у вас мысли верные есть, я не берусь это анализировать. Но изложить эти мысли вы не смогли.
                                Что, кстати, довольно странно учитывая вашу фразу:
                                Я бизнес-аналитик, уже десять лет работаю в области разработки заказного программного обеспечения, в последнее время совмещаю роли аналитика и руководителя проектов.
                                • 0
                                  Хм. А какая документация у вас пишется?
                                  Можете рассказать о структуре, назначении и авторах? Это я не из язвительности, а из любопытства интересуюсь.

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

                                  Про назначение документов могу рассказать, если интересно.
                                  • 0
                                    1) Концепция — на этапе пресейла, если проект большой. Фиксирует заинтересованные стороны, бизнес-цели, верхнеуровневую архитектуру. Пишет аналитик и немного архитектор.
                                    2) Техническое задание — в основном если требует заказчик. Пишет аналитик и архитектор.
                                    3) Методика испытаний — пишется если заказчик дает непонятное ТЗ, пишется аналитиком.

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

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

                                    Внутренних документов нет. Все ведется в TFS.
                                    Еще на доске рисуем иногда. Доску все видят — хорошо помогает.
                                    • 0
                                      Вы утвердили меня во мнении, что оперируете только гостовыми терминами.
                                      Описание в TFS Вы документами не считаете?

                                      Я осознанно опущу вопрос о практике разработки в отсутствии ТЗ, это, безусловно, дело сугубо личное…
                                      • 0
                                        Какое описание? В TFS есть стори, таски, баги. Это не документы. Они неотчуждаемы.
                            • +1
                              А почему вы не описываете варианты использования в виде текстовых сценариев, как учит нас пророк юзкейсов Алистер Коберн?
                              • 0
                                Я не люблю текст :)
                                Считаю, что блок-схема плюс табличное описание более наглядно, чем «простыня» из букв.
                              • +1
                                Очень интересно будет почитать про автоматизацию составления руководства пользователя, равно как и руководства администратора! Спасибо за статью

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