Boatman's Home:  О сайте   Новости   Карта  
Статьи и заметки о менеджменте и системном анализе в ИТ + мысли о трудовых отношениях, рынках труда, услуг и программных продуктов
Это страница на старом движке. Новые статьи здесь
2008-07-07 00:54    Boatman   Обсудить в Google Groups   Перейти на страницу обсуждений

Данная статья создана для размещения на сайте boatmanshome.ru. Автор и обладатель исключительного права на эту статью - Нужненко Сергей Александрович.
Для данной статьи автор разрешает размещение ссылок и цитирование, а так же воспроизведение в личных и учебных целях.
Без согласования с автором запрещается для данной статьи или любой ее части воспроизведение в коммерческих целях, а так же любые распространение, публичный показ, импорт с целью распространения, прокат, переработка, сообщение для всеобщего сведения.
Для согласования видов использования статьи можно связаться с автором по e-mail: haron@ru.ru с пометкой в теме "Boatmanshome-text-use".

Создание эффективной инженерной документации

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

Введение  ^

Материал этой статьи родился постепенно. Сначала была статья "К вопросу о диаграммах", раскрывающая роль диаграмм в процессе разработки ПО. Некоторые разделы статьи, посвященные процессу коммуникации, оказались общими для любых документов в любом виде. Там же сделана попытка сравнительного анализа графического, текстового и табличного представления данных.
Чуть позже, а именно 28 июля 2008г. я принял участие в тренинговом марафоне Traininglabs 2008 с тренингом на тему "Создание эффективной инженерной документации". В разминке тренинга была деловая игра, основой которой стало сравнение трех видов представления информации, из статьи, описанной выше. К моему стыду подготовленный материал немножко не удалось уместить в 1.5 часа тренинга и в конце я пообещал участникам написать статью по материалам тренинга, чтобы восполнить пробел для всех заинтересованных хотя бы в теоретической части.
Однако чуть раньше тренинга была еще одна короткая заметка с провокационным названием: Народ! Я изобрел проектное управление... Заметка получила множество откликов, где наряду с обвинением в поверхностности был поставлен на вид пробел и в описании документирования. В результате получилось, что данная статья восполняет этот пробел.

Кому это нужно  ^

Учитывая то, что статья фактически является текстом доклада к теоретической части тренинга, начнем с анонса тренинга и разбора актуальности проблемы:
Частая проблема проектов, использующих гибкие методологии разработки ПО заключается в том, что под лозунгом "каждому проекту своя методология" понимается, в частности, полное отрицание документирования, когда шаблоны документов из "тяжелых методологий" громоздки и неудобны, а новых нет и не будет.
Причина в том, что методика создания полезных и максимально простых инженерных документов, отвечающих условиям их применения, не оформлена в виде отдельной дисциплины.
Любой опытный инженер, аналитик или менеджер знает простые правила создания эффективной документации, но они достались ему по крупицам из разных источников и собственного (в том числе и негативного) опыта.
Данный тренинг призван собрать воедино правила планирования и создания максимально эффективных документов, а также закрепить полученные знания при выполнении практических заданий.
Действительно, в маленьких проектах (это когда на все про все есть 3-4 месяца и полтора человека) зачастую очень трудно объяснить своим полутора разработчикам, зачем заполнять эти шаблоны из тяжеленной методологии, что они дадут проекту. И выбор стоит между писать документ или не писать документ. Экзотическое совмещение ролей на проекте помещает несколько участников процесса в одну голову, кажется, отменяя необходимость создания некоторых документов, посредством которых общаются проектные роли. При попытке волевым решением применить какие-то документы обнаруживается, что документы устаревают быстрее, чем удается их согласовать и утвердить.
При отказе от документации к концу 5-го или 6-го месяца разработки можно обнаружить, что проект уже вышел за сроки на 50% и назвать точную дату его завершения не представляется возможным, так как мы не до конца представляем себе требования, архитектура внутренне противоречива, а количество и качество дефектов не поддается контролю. Разработчики утверждают, что заказчик уже 4-й раз меняет свои решения, при том, что где-то со второго или третьего раза разработка ходит по кругу.
Достаточно часто встречается случай, когда требуется повышение эффективности в процессах, поставленных на уровне ремесленной мастерской (это когда полный цикл отрабатывают те же полтора человека). Как только требуется постановка более четкого взаимодействия даже двух-трех человек, все упирается в документирование планов и решений. В этой ситуации попытка внедрить систему документирования от какой либо тяжелой методологии (например, PMBOK) терпит крушение из-за чрезмерной сложности шаблонов и недостаточного понимания пользы от этой громадной пачки бумаги. Достаточно часто при не очень четкой проработке системы документирования из тяжелой методологии выкидывают нужные данному процессу документы.
Список примеров можно продолжать и дальше, однако закончу таким вопросом: кто из начинающих аналитиков не задавал себе вопроса: "Как правильно писать ТЗ по ГОСТ 34.602?" - этому посвящены множество обсуждений на форумах, статьи и даже тренинги и все же каждый раз при написании ТЗ мы снова задаем себе этот вопрос. Почему? Ответ прост: все зависит от... Все зависит от ситуации, и конкретного назначения этого самого ТЗ. Как такое может быть, когда назначение ТЗ описано в самом ГОСТ 34.602?
Опытные аналитики и менеджеры согласятся со мной, что есть две большие разницы между ТЗ по ГОСТ 34.602, которое будет оценивать тендерная комиссия при организации конкурса на получение госзаказа, и ТЗ по ГОСТ 34.602, которое будет приложено к договору на разработку автоматизированной системы для коммерческого заказчика. Кроме этого есть ТЗ по ГОСТ 34.602, появляющееся в результате отдельного подпроекта по написанию ТЗ по ГОСТ 34.602, а еще есть разные виды автоматизированных систем, в которых действуют разные традиции, умолчания и окружающие условия. И этот список можно продолжать бесконечно, так как мы еще не затрагивали распределение ролей заказчика, потребителя и исполнителя на разные юридические лица и другие факторы, влияющие на условия написания одного единственного документа.

Надеюсь, читатель достаточно убежден в том, что отсутствие документирования, мягко говоря, не всегда ведет к успеху.
Почему же нам не всегда подходят имеющиеся шаблоны? Ответ прост: достаточно давно было замечено, что вовлеченность в построение нового порядка облегчает участникам принятие этого порядка. Чужие шаблоны не оптимизированы под требуемые процессы, часто там не учтены некоторые тонкости и детали, туда не включены разделы, требуемые в данном случае, в другие же нечего писать. Но еще чаще шаблоны чудовищно избыточны, разработаны под ситуацию с минимальным совмещением проектных ролей, и, следовательно, не годятся для маленьких проектов, в которых потеря одной-трех человеко-недель только на обкатку чужих шаблонов составляет не 1-2% общей плановой трудоемкости, а все 10-15%, превращаясь в существенный фактор риска нарушения сроков и бюджета, не говоря уже об издержках, вызванных частью документов, ненужных в данном случае.

Что это такое  ^

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

Теория  ^

Что такое документ  ^

Существует множество определений документа. Приведем краткие выжимки из словарных статей, содержащие важные для нас факты:
Большой юридический словарь Зафиксированная на материальном носителе информация с реквизитами, позволяющими ее идентифицировать
Информатика. Энциклопедический систематизированный словарь-справочник Материальный носитель информации, зафиксированной вне памяти человека
Современный экономический словарь Деловая бумага, юридически подтверждающая определенные права ее обладателей, фиксирующая, удостоверяющая определенные факты, события
Можно четко выделить 3 ключевых свойства, отличающих документ:
- информация на носителе вне памяти человека;
- наличие идентифицирующих реквизитов;
- подтверждение прав, фиксация событий и фактов.
Разберем выделенные свойства подробнее.
Информация на носителе вне памяти человека. Учитывая то, что информация всегда находится на каком-либо носителе, самым важным в документе является то, что эта информация находится вне памяти человека. Человеческая память ненадежна сама по себе. Кроме этого доступ к хранящейся там информации проходит через множество фильтров, связанных с текущими оценками, целями, интересами и эмоциями, что делает процесс извлечения неповторяемым. Информация, однажды извлеченная и помещенная вне памяти человека начинает жить собственной жизнью. Многие техники целеполагания и принятия решений, предлагаемые нам психологами и консультантами от менеджмента связаны с записью планов, наблюдений и решений и последующим их анализом.
Наличие идентифицирующих реквизитов совместно с границей, определяемой носителем, привязывает некоторый объем информации во времени и пространстве (как физическом, так и информационном). Такая привязка позволяет нам получить следующее важное свойство документа:
подтверждение прав, фиксация событий и фактов. Естественно, информация может носить и другой характер, но для деловой практики именно такое наполнение документов является наиболее ценным.

Инженерный документ  ^

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

Система документирования  ^

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

Процессный подход  ^

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

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

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

Контекст документа и источники информации  ^

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

Концепция трассировки и информационная схема документа  ^

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

Информационная схема документа  ^

Трассировка (причинно-следственная связь) возникает при рассмотрении документа в процессе его создания. Если мы уберем причину, то исчезнет и следствие - вот, что говорит нам трассировка. Однако при взгляде на документ, как на модель, несущую информацию об окружающем мире, мы можем видеть, что каждая связь между частями документа несет смысловую нагрузку, определяемую связями объектов реального мира. Структурированный документ можно рассматривать как базу данных, содержащую информацию для ответов на вопросы. Для примера приведем информационную схему протокола совещания.
На диаграмме представлена информационная схема сущность-связь в нотации IDEF1 с некоторыми добавлениями. Черные связи соответствуют информационным связям между частями протокола, голубые стрелки - направления трассировки, причинно-следственные связи между информационными элементами.
Части протокола связаны между собой и с другими документами. Так, ФИО участников и в списке рассылки обязательно будут содержаться в перечне проектной группы, название проекта точно указано в приказе о старте проекта, а решения должны быть привязаны к вопросам повестки.
Любой документ, полезный в процессе работы, имеет информационную схему, связывающую между собой различные части документа. Польза от такой схемы в том, что она в сжатом виде показывает, на какие вопросы может отвечать документ, а на какие не может, кроме этого схема позволяет уточнить последовательность заполнения шаблона, явно отображая трассировки.
При необходимости, информационная схема может быть составлена для пакета документов, тогда на ней видны не только внутренние связи документа, но и внешние связи одних документов с другими. Ценность таких схем, как и в предыдущем случае заключается как в ясном представлении вопросов, отражаемых в документах, так и в возможности проверки планируемого процесса разработки пакета документов.
Конечно, детальная информационная схема, выполненная по правилам проектирования баз данных может оказаться избыточной во многих случаях, часто достаточно концептуальной модели сущность-связь, пример которой без комментариев я привожу ниже.

Способы представления информации  ^

При создании шаблона документа перед составителем стоит выбор, какие виды представления выбрать для отражения информации. Выбор, в большинстве случаев, производится из трех видов представления: текст, таблицы, диаграммы. Существуют и более узкоспециальные способы представления информации, но здесь мы их рассматривать не будем. В статье "К вопросу о диаграммах" приведено сравнение видов представления с примерами. Здесь же будут даны только сводные результаты:
Текст Таблица Диаграмма
Описательная способность + +- -
Однозначность + +- -
Минимальная избыточность - +- +
Наглядность - +- +
Минимальные нарушения целостности - +- +
Скорость поиска фактов - + +-
Анализ сложных связей - - +
Минимальный объем контекста + +- -
Минимальное замедление работы с документом при росте объема - + +-
Возможности машинной обработки - + +-
Чтение без подготовки + + -
В таблице дано сочетание трех видов представления информации и параметров, важных для составителя и потребителя документа. Знаком "+" отмечено наиболее благоприятное значение параметра, знаком "+-" - среднее, и знаком "-" - наименее благоприятное. Можно видеть, что однозначных лидеров нет. Текст предельно однозначен, имеет неограниченную описательную способность и требует минимального объема контекста. Таблица оптимизирована для поиска фактов и сохранения своих возможностей с ростом размера. Диаграмма максимально наглядна, неизбыточна и оптимизирована для анализа связей.
В зависимости от ситуации для разных документов (разных частей документа) применяются различные виды представления информации.

Шаблон документа  ^

Возможность существования шаблона документа определена возможностью существования его информационной схемы. Если сказать проще, когда в ряде документов могут быть выделены одинаковые по назначению, отвечаемым вопросам и информационным связям части, для этого ряда документов может быть составлен шаблон, содержащий разметку для информационных частей и связи. Шаблон также может быть составлен, если информационная схема может появиться раньше сбора фактов, помещаемых в документ. В случае одного документа шаблон будет называться "рыба" или план документа.
Чем полезен шаблон? Шаблон позволяет ничего не забыть при составлении документа. Как говорят: "рыба документа задает вопросы.", а нам остается только собрать информацию для ответа на них. Шаблон полезен как тем, что управляет процессом сбора информации и составления документа, так и тем, что мы не тратим время на планирование документа заново.
В чем же "кидок"? Естественно, за все надо платить. И такой расплатой за пользу от шаблона документа является то, что к шаблону требуется инструкция по заполнению, без которой однозначно правильно его заполнить не удастся. Эта инструкция может быть или в письменном виде или в голове составителя, но то, что она должна быть - не подлежит сомнению. Часто в обычной жизни нам приходится заполнять всяческие анкеты и бланки, каждый хотя бы несколько раз спрашивал себя или окружающих: что писать в эту графу, можно ли ее оставить пустой, или куда писать какую-то конкретную информацию.
Но даже при наличии инструкций по заполнению, прилагающихся к шаблонам из какой-либо методологии, все равно остается риск неоднозначного или неправильного толкования этих инструкций. Типичный пример: все тот же ГОСТ серии 34, регламентирующий разработку автоматизированных систем. Вроде бы в ГОСТе все написано, как составлять те или иные документы, однако на практике этого недостаточно, и понимание "как все таки это делать" приходит к разработчикам только с опытом.
Практически всегда при работе с новыми шаблонами целесообразно осуществить быструю "пересборку" этих шаблонов, пройдя путь от явного определения назначения и области применения документа, извлечения из шаблонов информационной схемы, определения источников информации и контекста, и пересоставления шаблонов с параллельной конкретизацией инструкции по заполнению под имеющуюся ситуацию.

Принципы оформления  ^

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

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

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

Разумная бюрократия: принципы согласования документов  ^

Некоторые объемные документы перед получением статуса утвержденной окончательной редакции должны пройти процедуру согласования. Лист согласования может содержать десятки позиций и не все рецензенты одинаково лояльно настроены по отношению к ответственности, решениям и обязательствам, связанным с подписанием документа. Для борьбы с упрямыми согласующими и для упорядочивания работы при большом списке согласования давно придуманы формальные методы согласования документов. Приблизительная схема процесса формального согласования представлена на рисунке ниже.
После разработки документа, его копии отсылаются всем рецензентам, которые обязаны составить список замечаний в специальном формате. Основная идея в том, что нельзя критиковать, ничего не давая взамен. Поэтому список замечаний должен содержать указание на часть документа (номер абзаца, пункт перечня, ячейку таблицы или номер рисунка) и предложение нового текста (изменения в рисунке).
После получения замечаний, специалист, ответственный за согласование сводит замечание в одну ленту, где указано имя рецензента, место в документе, старый текст и новый текст, после чего составители документа, пройдя по сводке, могут принять предварительные решения: вносить предложенное изменение или не вносить.
По всем спорным изменениям должна быть проведена работа с рецензентами: переписка, телефонные переговоры или очное общение. В идеальном случае замечания рецензентов не влияют друг на друга и принимаются составителями документа, тогда надо просто внести изменения.
В случае похуже требуется собрать совещания и по каждому пункту сводки принять решение, где-то заставив рецензентов отказаться от замечаний, где-то выработав окончательные формулировки. Очень важно зафиксировать решения протоколом - это не позволит рецензентам выдвигать повторно одни и те же замечания или менять мнение на противоположное несколько раз. В случае пересечения интересов, у разных заинтересованных лиц появляется возможность договариваться напрямую. Иногда требуется несколько совещаний и подъем вопроса на уровень выше. В любом случае главное - четкая протокольная фиксация как сути замечаний, так и решений.
Практика показывает, что в большинстве случаев за 2-3 оборота по такой схеме можно согласовать большинство документов.
Такая схема может сильно сберечь нервы и даже деньги при работе в режиме Заказчик-Исполнитель, когда сроки закрытия договорных этапов сильно зависят от скорости согласования разрабатываемых документов (например, ТЗ). В таких случаях разработка, рецензирование, принятие решений по замечаниям должны быть явно вписаны в план работ (утвержденный заказчиком) вместе с пакетом условий:
- замечания после срока рецензирования не принимаются (или сроки оставшихся работ переносятся по вине заказчика, то есть без штрафных санкций для исполнителя);
- заказчик обязан организовать принятие решений по замечаниям в указанные сроки;
- заказчик обязан организовать подписание документа на основании протокола по замечаниям и документа с внесенными изменениями.
Естественно, жесткость схемы согласования можно регулировать в зависимости от ситуации, но даже в самом мягком варианте хорошим тоном считается возврат замечаний в виде перечня, а не заметками в тексте и на полях копии документа.

Виды решений, подлежащие документированию в ИТ проекте  ^

Маленький проект предполагает сильное совмещение ролей, повышенные требования к эффективности документирования и повышенную чувствительность к избыточному и неудобному документированию.
Следует понимать, что избыточность документирования - вещь субъективная. Для кого-то составление и рассылка неформального (без подписей) полустраничного протокола ежедневных совещаний занимает 5 минут в день и не считается чем-то обременительным, для кого-то другого это кажется излишней бюрократией. Естественно, кто-то другой мог бы составлять эти протоколы, но он не вполне дружен с литературным языком, боится показать это коллегам, испытывает что-то похожее на проектный паралич перед чистым листом бумаги и тратит на такой документ все 30, а то и 60 минут.
Я думаю, все согласятся с утверждением, что как хороший менеджер, так и хороший инженер обязаны уметь излагать свои мысли в письменном виде четко, грамотно и быстро, не делая из документирования камня преткновения. Основа как инженерного дела, так и регулярного менеджмента в повторяемости и измеряемости, которые не могут быть достигнуты без документальной фиксации фактов и решений. А потому, я думаю, вопросом является не "что документировать", а как документировать.
Если говорить о времени, то приверженцами тайм-менеджмента (см здесь) доказано, что хронометраж (отчетность о выполнении деятельности) достижим с разрешением до 5 минут. Планы могут иметь деление на 15ти минутные отрезки. Однако это крайности. В действительности вполне достаточно и целесообразно почасовое планирование и отчетность, что вполне достижимо, малообременительно (в рабочем дне всего лишь 8 часов, в неделе - 40) и применяется повсеместно в организациях, достигших определенного уровня зрелости. И в любом случае, обязательства и решения, касающиеся более 2х человек и имеющие срок жизни больше 1-2х недель следует фиксировать в документе (при этом не всегда обязательно соблюдать строгую форму и ставить подпись).
Если говорить о детализации целей, требований и ключевых технических решений, то ее снижение нежелательно. Требования пользователей лучше формулировать с точностью до макетов интерфейса, насколько это вообще возможно, желательно иметь ответы на вопросы по основным и альтернативным сценариям поведения системы (что система должна делать в нормальном случае и если что-то идет не так). Цели желательно формулировать на уровне четко измеряемых численных показателей. Желательно иметь точный контрольный список приемки системы, на основании которого мы сможем осуществить ее сдачу заказчику. Какой бы простой не была система, желательно иметь инструкцию пользователя, администратора и другие виды эксплуатационной документации.
Отсутствие четкой и детализированной документации часто означает отсутствие четких и детализированных мыслей, что означает отсутствие конкретных и однозначных планов и решений. Однако документация в маленьком проекте должна отличаться от документации в большом, так как она имеет меньший объем и служит для коммуникации меньшего количества людей.
На чем же можно сэкономить? В маленьких проектах обычно разрабатываются системы небольшого масштаба, которые не требуют для описания толстых пачек документации. Как следствие, мы можем уменьшить издержки на документирование, сэкономив на тех частях документов, которые служат оптимизации поиска в больших пакетах документов. Кроме этого, разбиение пакета документации на отдельные документы диктуется порядком разработки и согласования документов: различными составителями и разделением ответственности за принятые решения. Малая численность команды, малая длительность проекта и конкретные особенности ситуации позволят вынести некоторые вопросы в контекст, в частности, пренебрегая обширным глоссарием.
Если учесть, что разделы с назначением, областью применения, обзором, содержанием и списком ссылочных документов занимают 2-3 страницы, а в маленьком проекте концепция, требования и архитектурные решения могут сами занимать в среднем по 3-10 страниц, мы можем сэкономить от 20 до 50% объема, объединив три документа в 1.
Учитывая небольшой объем требований и простоту архитектуры, в маленьких системах можно пренебречь систематизацией исходных требований (отказаться от формального получения системных требований из бизнес-требований с подробным документированием), также можно отказаться от документирования архитектуры, которая будет ясна из исходного кода и артефактов, поступающих непосредственно на вход сборки. Такой шаг позволит убрать еще 50-70% объема, что сделает процесс документирования необременительным.
Малый объем требований и решений позволяет несколько снизить требования к систематизации, отменяя работу по разделению информации и раскладыванию по полочкам разных разделов обширного документа. Такое отсутствие систематизации может оказать медвежью услугу, если выяснится, что мы учли не все, отказавшись от шаблона, неизбежно задающего все важные на данном этапе вопросы. В результате можно выдвинуть такую рекомендацию: отсутствие систематизации в документе допустимо, если его объем мал и позволяет прочесть документ и построить быстро в голове (или на паре листиков бумаги) модель, позволяющую проверить информацию на полноту и непротиворечивость.
Еще одним важным фактором, влияющим на документирование маленького проекта является скорость и объем поступления изменений в целях и требованиях. Чем чаще меняются требования, тем выше издержки (неподъемные для маленьких проектов) на переработку вторичных документов: системных требований, архитектурных документов и излишне детальных планов. Даже при теоретической неизменности бизнес-требований изменения могут возникать из-за того, что сбор требований идет параллельно с разработкой, в результате чего список бизнес-требований непрерывно пополняется, вызывая изменения в архитектурных решениях.
Плюсом маленьких проектов по отношению к изменениям требований как раз является принципиальная возможность отказаться от поддержания промежуточных (производных) документов. Кроме этого, процесс изменения исходных документов может быть менее формальным и не требовать длительного пересогласования каких бы то ни было документов.
Учитывая написанное выше, я составил следующий список вопросов, подлежащих документированию в маленьком проекте с рекомендациями:
Цели: с точностью до показателей достижения и концептуальное описание результата;
Бизнес-Требования: детальные требования на уровне "что сказали потребители" - лучше иметь протоколы интервью и совещаний, опросные листы и другие материалы, содержащие необходимую информацию.
Планы: ничто не мешает иметь маленький план маленького проекта на уровне договорных этапов или ключевых событий внутри этапа и быстроизменяемый список оперативных задач с почасовым учетом времени;
Эксплуатационная документация: в полном объеме, необходимом потребителям;
Системные требования и архитектура: могут быть в виде черновых набросков для внутреннего использования или отсутствовать;
Обнаруженные дефекты и изменения (дополнения) бизнес-требований: в полном объеме;
Значимые решения и результаты работ, утверждаемые заказчиком: например, в виде протоколов.
Документ, управляющий тестированием: Как минимум в объеме, необходимом для формальной приемки.

Технология создания системы документирования  ^

Выше были описаны теоретические концепции, сопровождающие построение эффективной системы документирования. В этом разделе дано краткое описание практических шагов по построению системы документирования или по созданию одного документа:
1. Определение структуры пакета документов
1.1. Кратко описать цели проекта или регулярной деятельности Для того, чтобы документы соответствовали целям конкретного проекта.
1.2. Описать состав участников и распределение ответственности, чтобы найти подход к разделению всей фиксируемой информации на отдельные документы.
1.3. Кратко описать процесс производства работ. В описании процесса будет ясно, кто, когда и какие документы составляет, а также назначение и области применения конкретных документов. Следует учесть рекомендации по документированию в маленьком проекте, приведенные выше.
1.4. Определить состав документов и виды документируемых фактов и решений на основании составленного описания процесса производства работ.
2. Для каждого документа
2.1. Описать назначение документов Которое мы определили в шагах 1.3 и 1.4.
2.2. Описать область применения документов Которую мы определили в шагах 1.3 и 1.4.
2.3. Описать источники информации: документы - основания разработки и контекст На основании схемы процесса производства работ.
2.4. Создать схему документа Пользуясь списком отвечаемых вопросов из шагов 1.4 и 2.1
2.5. Создать шаблон документа на основании схемы документа, комбинации различных видов представления информации и рекомендаций по оформлению.
2.6. Написать обзор документа на основании схемы и шаблона документа.
3. Дополнительно
3.1. Проанализировать трассировки между документами и частями документов Проверяя возможность получения информации для документов в данной точке рабочего процесса и составляя детальную инструкцию по заполнению.
3.2. Детально спланировать процессы сбора информации-создания-согласования Продолжая проверять возможности получения необходимой информации и корректируя шаблон с учетом особенностей согласования в данном случае.
3.3. Собрать информацию и оформить документ, корректируя схему документа и шаблон при необходимости.
Представленный процесс не является прямолинейным. На каждом шаге мы можем получить несоответствие: понимание того, что чего-то не хватает в схеме документа или в рабочем процессе. Сквозное планирование пакета документов вместе с рабочим процессом позволяет нам улучшить как документацию, так и процессы, сопровождающие ее создание. В результате на каждом шаге можно вернуться для того, чтобы внести исправления в план рабочего процесса, схемы и шаблоны документов.
Применение технологии на этапе планирования проекта может помочь не только обнаружить риски и пропущенные работы, но и смоделировать объемы работ, связанные со сбором информации и созданием-согласованием документов, что повысит точность планирования в целом. Точно так же работа с использованием документации может сделать процесс работы более прозрачным и предсказуемым.

Заключение  ^

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

P.S.  ^

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