Документация по проекту: как практические рекомендации могут обеспечить успех

В недавнем выпуске нашего популярного еженедельного информационного бюллетеня WServerNews я рассказал о том, почему крупные ИТ-проекты часто терпят неудачу. Это вызвало оживленную дискуссию наших читателей, но также заставило меня задуматься. Может ли быть так, что плохая практика документирования может быть одним из факторов, способствующих провалу многих ИТ-проектов? Чтобы получить некоторое представление об этом вопросе, я обратился к Джону Цитрону, который много лет работал в области сетевого администрирования и ИТ-поддержки и участвовал в многочисленных обновлениях инфраструктуры, миграции и развертывании. Хотя сейчас Джон на пенсии и посвящает свою жизнь изучению музыки и другим увлечениям, его мир информационных технологий начался почти 40 лет назад в качестве сборщика печатных плат, где он вскоре продвинулся по карьерной лестнице, пройдя курсы аналоговой и цифровой электроники. Джон говорит, что поначалу он никогда особо не интересовался этой сферой, но увлекся ею и оставался в ней до конца своей трудовой жизни. В какой-то момент он даже работал на некоторых из уже давно ушедших производителей аппаратного обеспечения, включая Visual Technology, Infinet и Datawatch. Как техник, ответственный за ремонт первых персональных компьютеров, он изучил MS-DOS и CP/M, а позже посещал курсы программирования по сборке Z80 и 8080. Как только рабочие места техников исчезли, Джон перешел к MIS и компьютерным операциям, где он управлял компьютерными комнатами, полными DEC VAX с VMS и Ultrix, системами Sun OS и даже небольшим количеством IBM MVS / TSO, OS / 2, ROSCO, а затем и Solaris. и Novell Netware. По мере того, как время шло, и отрасль перешла от централизованных операций к средам рабочих групп, Джон последовал этой тенденции и, проработав некоторое время в семейном графическом бизнесе в качестве наборщика, используя проприетарную систему Varityper Epics 20/20 и работая в области сетевого администрирования и настольных компьютеров. поддержки, он окончательно вышел на пенсию в 2012 году. Поэтому я могу с уверенностью сказать, что знания и опыт Джона в области ИТ и управления проектами являются глубокими и сильными. Теперь давайте передадим слово Джону и послушаем, что он может сказать о том, как правильное документирование ИТ-проектов может обеспечить успех.

Документирование ИТ-проектов: как сделать хорошее практическое руководство

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

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

Имея это в виду, почему бы не отказаться от этой тенденции и не изложить все в письменной форме? Но документирование проектов в области ИС само по себе требует последовательного процесса. Много лет назад я работал оператором ЭВМ с очень сложными ежедневными операциями. Чтобы гарантировать, что каждый процесс выполняется последовательно и точно каждый раз, были установлены процедуры. Со временем различные операторы придумывали свои собственные методы ведения дел. Это приводило к ошибкам и откровенным сбоям, поскольку шаги были пропущены или забыты.

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

1. Установить систему пересмотра документов.
2. Используйте шаблон.
3. Сформулируйте обзор.
4. Создайте пошаговый процесс.
5. Тестируйте процедуры.
6. Попросите кого-нибудь или группу людей, не знакомых с процессом, протестировать процедуру.
7. Протестируйте снова.
8. Освободите документ для использования.

1. Установите систему пересмотра документации

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

Например, в одной организации, где я работал, у нас был сервер документов, который проставлял дату и создавал для нас все номера версий. На другом рабочем месте я просто использовал DD-MM-YY — Rev X с названием документации в нижнем колонтитуле шаблона документа и именем документа.

Пример:

2. Используйте шаблон

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

3. Сделайте обзор

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

4. Создайте пошаговый процесс

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

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

При написании используйте картинки, если это возможно. С изобретением утилит захвата экрана, таких как Windows Snipping-tool, Snagit или других подобных инструментов для других платформ, у нас нет оправдания не включать изображения или диаграммы в нашу документацию. Используйте текстовый процессор, такой как Apache OpenOffice Writer или Microsoft Office, или любой другой, доступный на используемой вами платформе. Эти программы имеют возможность вставлять встроенные скриншоты с субтитрами и текстовыми функциями. Скриншот внутри текста, а не в нижней части страницы, сохраняет целостность документа. Нет ничего хуже, чем пролистывать несколько страниц вперед и назад, чтобы найти изображение. Способы выпуска документов сильно изменились с 1992 года, когда мы использовали только текстовую систему! С сегодняшним онлайн-средой, HTML-форматированием, вики-форматированием и т. д. в вашем распоряжении множество площадок для ваших работ, так что используйте эту возможность.

5, 6 и 7. Тестировать, тестировать и еще раз тестировать

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

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

8. Выпустите документацию

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

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