Новости
02.03.2024
«Настоящий CTO: думай как технический директор»
Автор приводит мнения отраслевых экспертов и опытных CTO и делится практическими стратегиями навигации в мире технологического лидерства, где ставки чрезвычайно высоки.
Книга на примерах из реальной практики показывает, как преуспеть в быстро меняющейся роли технического директора. Прочитав ее, вы научитесь создавать успешные технологические платформы и формировать эффективные команды, грамотно выбирать и внедрять программные продукты, проводить собеседования и перформанс ревью в беспристрастной манере, а также сможете по праву занять место за столом топ-менеджмента. Вы оцените деловые советы, идеи и истории из практики от наставника CTO Алана Уильямсона.
Для кого эта книга
Если вы принадлежите к одной из следующих категорий, значит, вы выбрали правильную книгу:
- Опытный технический специалист, желающий перейти на следующую ступень карьеры — к роли технического директора.
- Технический директор, впервые оказавшийся на этой должности и желающий убедиться, что он делает все от него зависящее.
- Опытный технический директор, чья компания быстро растет и у которого нет ответов на задаваемые вопросы.
- Технический директор, который пришел на смену предыдущему и от которого руководство ждет больших, революционных изменений.
- Генеральный или финансовый директор, пытающийся решить, необходим ли компании технический директор (и чем он будет заниматься), и если да, то как подобрать человека на эту должность.
Зачем составлять документацию?
Зачем эти хлопоты? Ведь ваша команда знает, как все устроено, — это знание передается из поколения в поколение. Кроме того, ваш технологический стек так грамотно спроектирован и внедрен, что в нем разберется любой толковый специалист. Если вы так думаете, то, вероятно, еще и уверены, что ваш код не содержит ошибок и, следовательно, не требует тестирования! Звучит абсурдно, но многие действительно так считают.
Документация — это преемственность. Документация — это масштабируемость. Документация — это свобода. Это не признак слабости и не формалистская рутина, которую приходится терпеть и которую можно откладывать на самый последний момент.
Независимо от того, насколько современна ваша архитектура и читабелен ваш код, существуют правила и логика, применимые только к вашей организации. Нельзя понять, почему были приняты те или иные проектные решения, только читая код. Документация — это руководство по эксплуатации вашей системы, и без документации никто не сможет в полной мере воспользоваться всеми ее возможностями.
Люди забывают детали. По мере того как дни складываются в недели, недели — в месяцы, а месяцы — в годы, забывается причина, по которой что-то было сделано именно так, а не иначе. Нестандартное бизнес-правило или неочевидное ограничение, которое в свое время направило архитектуру/реализацию в ту или иную сторону (и в то время это решение было верным), в будущем может оказаться не столь понятным. С решениями, причины которых затерялись в прошлом, произойдет одно из двух:
- Новый сотрудник увидит его, подумает, что можно сделать все проще, переделает — и в итоге что-то сломается.
- Люди будут бояться трогать решение или тем более пытаться его переделать. Оно приобретет мифические свойства и будет считаться слишком сложным или важным, чтобы рисковать и вносить в него изменения.
Оба сценария несут большую опасность, и обоих можно полностью избежать, если оставить краткие пояснения. Как однажды заметил один мудрый разработчик: «Комментарии [в коде] — это любовные записки будущему самому себе».
11.1.1. Целевая аудитория
Документация — это не единая универсальная вещь, подходящая сразу для всех читателей. Это набор документов, предназначенных для разных групп получателей, в зависимости от того, как они взаимодействуют с системой. Вот какими могут быть эти группы:
- Конечные пользователи. Пользователи системы, взаимодействующие с готовым продуктом.
- Техподдержка. Сотрудники службы поддержки, которые помогают конечным пользователям с их вопросами.
- IT/DevOps. Команда, отвечающая за поддержание системы в рабочем состоянии.
- Разработчики. Команда, которая создает и исправляет функционал.
Чем больше и старше система, тем больше у каждой группы будет особых требований. В небольших командах, которые только начинают развитие своего проекта, одни и те же люди могут выполнять широкий спектр обязанностей, совмещая несколько ролей, а документация для конечного пользователя может вообще отсутствовать.
По мере роста у каждой группы появятся собственные процессы и зона ответственности, и ей будут требоваться поддержка и документация от более низкого уровня, на который она опирается. Наличие надежного источника информации поможет новым членам каждой группы (от конечного пользователя до разработчика) быстрее и успешнее адаптироваться к своим ролям.
Составляйте документацию на языке, понятном каждой группе, чтобы информация была более доступной. Например, описание алгоритмов не будет иметь особого смысла для конечного пользователя или сотрудников службы поддержки, но поможет разработчикам развивать и дорабатывать ПО. Точно так же подробные описания интерфейса и последовательности скриншотов не помогут команде IT/DevOps, потому что им на самом деле все равно, как выглядит приложение. Им необходимо знать, как, например, делать резервное копирование. Обращайтесь к конкретной аудитории.
11.1.2. Формат
Чаще всего документацию оформляют в классическом текстовом формате: такие документы легко создавать, читать, хранить, они не занимают много места, их легко искать и на них можно делать ссылки. Однако в последнее время набирают популярность видеоролики, записи сеанса работы с каким-либо инструментом, как будто ты смотришь через плечо человека, который это делает. Доступные инструменты для создания и редактирования коротких видео позволяют быстро записать и переслать или опубликовать их — а 5-минутный ролик может заменить несколько страниц подробного текста.
Хорошая документация должна быть легко доступна при необходимости. Какой бы хорошей ни была вещь, она практически бесполезна, если ее нельзя найти в тот момент, когда она нужна.
Документация в файлах PDF или DOC была актуальна 20 лет назад, но не сейчас. Документ, особенно предназначенный для обучения или описывающий работу платформы, должен быть живым. Его необходимо обновлять с каждым релизом или при появлении новых данных. И такое обновление не должно превращаться в отдельную большую задачу, оно должно делаться быстро и без усилий.
Когда Тим Бернерс-Ли (Tim Berners-Lee) создавал интернет, его целью было обеспечить удобный обмен информацией. Таким образом, логично организовать хранение документов на основе технологий интернета. Такие инструменты, как вики, Atlassian Confluence, Google Docs и Office 365, отлично подходят для работы в браузере. При выборе платформы для документации учитывайте следующее:
- Прямые ссылки на контент. Убедитесь, что пользователь может попасть в нужный раздел по ссылке и не требуется совершать несколько шагов, чтобы найти его.
- Организация связанного контента. Инструмент должен позволять легко объединить связанные области, чтобы читателю было удобно искать дополнительную информацию. В идеале это должно делаться автоматически, с помощью тегов или семантического анализа текста.
- Простое обновление. По мере появления новой информации контент необходимо обновлять, особенно если он предназначен для службы поддержки.
- Хранение предыдущих версий документа. Большинство современных инструментов уже поддерживают эту функцию. Возможность вернуться к предыдущей версии позволит постоянно дорабатывать документы, а читатели смогут определить, к какой версии продукта относится тот или иной контент.
- Безопасность. Не все документы должны быть общедоступны, поэтому необходимо иметь возможность ограничить доступ к определенным областям или разделам для конкретных групп пользователей.
- Обратная связь. Читатели должны иметь возможность оставлять комментарии или примечания, чтобы дополнять текст.
- Вложения. Насколько удобно прикреплять дополнительные файлы (изображения, видео, PDF)? Такие данные лучше хранить вместе с документом, к которому они относятся.
Хороший контент не обязательно должен быть безупречно оформлен — главное, чтобы он помогал читателю. Поощряйте каждого вносить свой вклад в формирование базы знаний — это залог того, что она будет полезной. Чем проще будет написание и дополнение документов, тем лучше.
11.1.3. Проверка
Мы все знаем о необходимости тестировать код перед релизом с помощью автоматизированных или чаще ручных тестов, проверяющих, что код делает именно то, что должен делать. Если вы хотите создать современную технологическую платформу, нельзя просто «надеяться», что все будет хорошо. То же самое касается и документов. Прежде чем документы начнут использоваться по назначению, необходимо проверить, насколько они полезны.
Все содержимое документов, особенно недавно написанных, кроме автора должен проверить еще кто-то, подтвердить нужность информации и убедиться, что документ не содержит слишком много пропусков или допущений с учетом его целевой аудитории и темы. Необязательно организовывать формальный процесс ревью — просто попросите еще кого-нибудь посмотреть текст.
Возьмем, к примеру, процесс релиза, включающий сборку, проверку и деплой вашей системы. Вместо того чтобы держать все в голове, разработчик этого процесса решил его описать. Как узнать, достаточно ли подробностей он зафиксировал? Нужно поручить кому-нибудь пройтись по документу (в идеале тому, кто не очень разбирается в предмете и не будет подсознательно заполнять пробелы в описании). Это лучший способ понять, решает ли документ свою задачу.
Особое внимание уделите описанию работы, которую обычно выполняет один человек, — все ли его действия зафиксированы верно, чтобы любой мог заменить этого сотрудника? Только проверив документацию, вы сможете с уверенностью ответить на этот вопрос.
11.2. Типы документации
В этом разделе мы рассмотрим, какие документы могут храниться в организации. Это не исчерпывающий список, а скорее ориентир, чтобы вы поняли, с чего начать.
11.2.1. Протоколы собраний
Собрания не должны быть частыми и многолюдными, поскольку они сильно отвлекают от работы и занимают много времени. Если вы решили, что собрание необходимо, оно должно быть максимально продуктивным.
У хорошего собрания должен быть один или несколько вопросов для обсуждения (или план встречи) и понятная цель. Собрания могут быть отличным способом обмена информацией, идеями и предложениями. Тем не менее, если на них почти или совсем не ведутся записи, много ценной информации упускается — и это большая потеря.
Протоколы собраний, подробно описывающие историю принятия тех или иных решений, должны стать частью вашей базы знаний. Некоторые организации ведут отдельный «журнал решений», подробно описывающий, почему договорились что-то делать именно так.
На каждом собрании назначайте кого-то, кто будет вести заметки, и предусмотрите время для их обработки. Можно вести записи в Google Doc в режиме реального времени, фиксируя ключевые моменты и решения. Если это быстрое собрание, посвященное разбору конкретной задачи, зафиксируйте все договоренности в комментариях к тикету в виде списка.
В постпандемийном мире многие собрания перешли в онлайн и проходят в режиме видеоконференций. В таком формате удобно записывать и хранить все ключевые встречи, чтобы не пропустить важные решения.
Сообщения в чате (Slack, Microsoft Teams и т. д.) также могут содержать ценную информацию. Пусть члены команды копируют ее и добавляют или в основную базу знаний, или в тикеты. Можно даже настроить ботов или плагины, чтобы вы могли быстро пометить сообщения, которые нужно отправить в отдельное хранилище.
11.2.2. Демонстрации продукта
Вспомните, сколько раз вы проводили демонстрацию продукта или показывали какой-то функционал по шагам. Записывалось ли это? При этом каждый следующий показ будет содержать что-то новое — или новый вопрос от зрителей, или новую информацию.
Полезно посмотреть рекламные ролики вашего продукта — так можно увидеть, каким образом отдел продаж продвигает его, и узнать, как его функции воспринимает клиент/пользователь и чего они ожидают от продукта. Ваши представления об этом могут значительно отличаться от клиентских.
Эти материалы помогают управляющей развитием продукта команде понять, что нужно пользователям, инженерам — что в продукте наиболее важно, и, наконец, новым членам команды — в создании чего они участвуют.
Объем информации со временем будет расти; не бойтесь этого. У таких материалов есть замечательный побочный эффект: они служат машиной времени, позволяющей новичкам ознакомиться со старыми версиями продукта и понять, как он эволюционировал.
11.2.3. Инструкции по использованию
Вероятно, один из самых важных документов — это тот, который объясняет, как поддерживать систему в рабочем состоянии, если хотите — инструкция по использованию. Он не про деплой кода. Это описание всех частей платформы и того, что они делают, как контролировать их состояние и что делать, чтобы снова запустить их в случае отключения электроэнергии (или выключения по другой причине).
Уровень детализации здесь должен быть достаточным, чтобы любой мог понять и выполнить нужные действия. Недостаточно просто написать: «Обязательно перезапустите компонент XYZ». Как перезапустить XYZ, какие команды нужно вводить и куда, как определить, успешно ли все прошло, и что делать в случае проблем? Такие детали часто пропускаются и хранятся только в чьей-то голове.
Например, во время запуска системы в консоли может выводиться много разной информации. Человек, не привыкший читать все эти строки, будет сбит с толку, он не будет понимать, что из этого хорошо, что плохо, а что можно игнорировать. Но если включить в документацию простой скриншот вывода, всего этого непонимания можно избежать и быть уверенным, что все работает правильно. Как известно, лучше один раз увидеть, чем сто раз услышать.
Руководство не должно быть многословным. Вы же не пишете очередную книгу о Гарри Поттере. Вы описываете, какие действия и в каком порядке нужно выполнить. Придерживайтесь простой структуры: нумерованный список шагов, для каждого из которых читатель должен понять, что нужно сделать, успешно ли все выполнилось и можно ли переходить к следующему шагу.
Также необходимо описать, как контролировать состояние системы: по каким признакам можно определить потенциальные проблемы? Сначала это может казаться сложным. Небольшой совет: попросите сотрудника, отвечающего за ту или иную часть комплекса, представить, что он уходит в отпуск, и написать электронное письмо тому, кто будет его замещать. Такой формат более привычен, и людям проще написать подробное электронное письмо, чем новую страницу вики или документ в Google Docs. Возьмите это письмо и добавьте его в базу знаний. Так можно делать много раз, и в результате вы соберете обширную, подробную библиотеку практических руководств.
Никто в команде не должен чувствовать, что единственная причина, по которой он здесь работает, — это его знание той или иной системы. Подобное отношение часто встречалось 10–20 лет назад, но сегодня это редкость. Люди ценятся не за информацию, которой они владеют, а за их вклад в общее дело команды.
Все мы любим работать с новыми модными технологиями — мы же инженеры. В нашем ДНК заложен постоянный поиск чего-то нового и лучшего. Важно описать работу существующих систем на таком уровне, чтобы никому не приходилось возиться с ними только потому, что больше никто этого не умеет.
11.2.4. Резервное копирование и восстановление
Часто в документации не уделяется необходимого внимания резервному копированию и восстановлению системы. Необходимо описать не только способ экспорта/импорта базы данных (хотя и это тоже). Речь об информационной системе в целом, от аппаратного обеспечения до операционных систем и ПО.
Что требуется, чтобы вернуть компонент к жизни? Какие части операционной системы нужны для запуска компонента? То, что кажется очевидным сегодня, может быть непонятно через месяцы или годы.
Заметки с полей
Дьявол в деталях
Несколько лет назад я столкнулся с ситуацией, когда попытки настроить новый сервер для генерации уменьшенных версий изображений зашли в тупик, потому что Java-приложение отказывалось работать. Оказалось, что для работы Java-приложения требовалось наличие ImageMagick — это популярная библиотека с открытым исходным кодом. Приложение не выводило достаточно информации для диагностики проблемы, хотя, конечно, должно было бы. Документация или какие-то подсказки также отсутствовали, и для того, чтобы выявить эту зависимость, пришлось декомпилировать приложение.
С ростом популярности контейнеров (таких, как Docker) зависимости на уровне операционной системы теперь обычно описываются как часть процесса сборки. Однако это не отменяет необходимости указать, что от чего зависит. Даже если все находится в контейнерах, необходимо описать, как контейнеры работают и взаимодействуют между собой, чтобы понять, как ими управлять. Должно быть достаточно информации, чтобы любой, кто разбирается в используемых технологиях, мог собрать компоненты системы из исходного кода. Если сейчас это невозможно, то у вас есть информационный долг. Разумеется, документы также необходимо обновлять с каждым релизом, по мере появления новых компонентов и замены или удаления старых.
Как я уже говорил, отрабатывать восстановление системы необходимо хотя бы раз в год, если не чаще. Если вы используете облачные сервисы, это можно делать без проблем, не мешая остальной работе и не подвергая риску продакшен. Полезно поручать новичкам выполнять сборку проекта с нуля. Это эффективный способ познакомить людей с процессом, показать взаимодействие компонентов и проверить актуальность документации.
11.2.5. Процесс деплоя
Релизы и обновления систем предприятия должны быть отлажены, предсказуемы и безопасны. Чтобы этого добиться, необходимы соответствующие инструменты и документация. Даже если вы полагаетесь на автоматизированный инструмент оркестрации (такой, как Jenkins), для его настройки в вашей среде все равно требуется руководство.
Оно должно содержать все необходимые шаги для подготовки сборки, с объяснением происходящих процессов, а также описанием критериев успеха или сбоев. Кроме того, следует указать порядок выполнения шагов и на каких этапах изменения можно безопасно отменить. Если у вас есть дополнительные процессы выпуска патчей, фиксов или релизов, то их тоже необходимо подробно описать.
Разработка надлежащей документации поможет информировать сотрудников и гарантирует, что релизы не будут зависеть от одного человека. Бывает такое, что компания может выпускать обновления, только когда старший специалист DevOps не в отпуске.
11.2.6. Комментарии в исходном коде
Если вы хотите вовлечь разработчиков в спор, по накалу страстей не уступающий легендарной дискуссии о табуляции и пробелах (кстати: пробелы), спросите, сколько комментариев должно быть в коде. Ответы будут варьироваться от «Моему коду комментарии не нужны — он и так понятен» до «Да уж, без комментариев тут не разберешься».
Чаще всего, если исходный код недостаточно очевиден и требует дополнительных комментариев — возникают вопросы «что» и «как». Реже бывает непонятно назначение чего-то и приходится пояснять «зачем».
Что?
Такой уровень детализации предназначен для других разработчиков, использующих эту часть кода. Например, это может быть библиотека с публичными функциями или методами, которые будут использоваться разработчиками других систем. Сюда также относятся API, которые используются какими-либо сервисами.
Для большинства современных языков существуют соглашения или специальный синтаксис, которые позволяют создавать документацию к вашей библиотеке из комментариев к функциям. Таким образом разработчики, импортировавшие библиотеку в свой проект, могут увидеть справку к ее методам с помощью встроенных в IDE механизмов автодополнения кода.
Отличным примером является язык Java, в котором есть стандарт для написания документации для классов и методов, он называется Javadoc. Такая документация не только показывается при использовании автодополнения кода и других функций IDE, на ее основе также можно сгенерировать набор веб-страниц с описанием исходного кода. Другой пример — библиотека Swagger, которая предназначена для создания документации в формате HTML для различных API, и, кроме этого, содержит инструменты для выполнения запросов к API для его тестирования или изучения.
Большое преимущество подобной документации состоит в том, что она находится в том же файле, что и код, поэтому ее легко обновлять. Документация в исходном коде очень важна, особенно для больших команд или в тех случаях, когда ваше API используется внешними клиентами.
Как?
Этот тип документации тоже находится в функциях и методах исходного кода и предназначен только для тех, кто разрабатывает этот код. Он не должен быть чересчур подробным. Работа грамотно спроектированного и хорошо написанного кода должна быть очевидна. Для этого необходимо использовать осмысленные имена функций и переменных, соответствующие их назначению, — в первую очередь необходимо стремиться к читабельности, а не к оптимизации. Тем не менее, если какая-то часть требует дополнительных пояснений, стоит добавить к ней несколько строк комментариев.
Идеальным будет оставлять в комментариях ссылки на тикеты — это поможет следующему разработчику лучше понять, почему компонент делает именно это. Какой-нибудь неочевидный оператор if можно легко объяснить, добавив номер тикета, и тогда следующий разработчик не будет его рефакторить в уверенности, что помогает проекту, но на самом деле добавляя еще больше проблем.
Убедитесь, что при ревью кода проверяется и достаточность комментариев. Когда разработчики привыкнут это делать, они уже не смогут работать без документации.
Зачем?
Если для чего-то недостаточно описать «как», то нужно объяснить «зачем», то есть для чего предназначена та или иная функция или система, обычно на гораздо более высоком уровне бизнес-логики. Обусловлено ли это на первый взгляд понятное техническое решение каким-то требованием бизнеса или это особенность работы одного из партнеров?
11.2.7. Схема архитектуры
Когда вам дарят коробку дорогих шоколадных конфет, на что вы смотрите в первую очередь? Конечно же, на схему, на которой указано, где лежат конфеты с разными начинками! Эта схема дает вам шанс избежать фундука, который прячется внутри. А истинные ценители шоколада используют ее для планирования своего гастрономического путешествия, ведь они хотят насладиться максимально насыщенным вкусом. Схемы и карты обеспечивают нас информацией, чтобы мы могли ориентироваться гораздо увереннее.
У вашей системы тоже должна быть такая «карта», или схема архитектуры. Когда вы знакомитесь с системой, всегда просите нарисовать ее схему на доске. Если в ответ вы получите недоуменные вопросительные взгляды, уточните: «Она состоит из прямоугольников и линий».
Это не должна быть сложная или формальная схема. Это не строительный чертеж, который должен соответствовать строгим стандартам. Это просто путеводитель, помогающий понять термины, в которых описывается платформа.
Здесь должны быть основные компоненты вашей системы, и если какие-то из них связаны между собой, то их нужно соединить на схеме линиями. Не вдавайтесь в подробности. На этом уровне достаточно знать, что File Microservice используется модулем обработки фотографий профиля пользователя. Сейчас не имеет значения, как он это делает — это может быть вызов API, очередь или просто общая папка. Такие подробности должны быть в других документах. Здесь же вы указываете — возвращаясь к аналогии с картой — только границы штатов, автомагистрали, показывающие, каким образом разные штаты связаны между собой, и самые крупные города.
Слишком много деталей тут не нужно, это перегружает карту и делает ее трудной для понимания. Для каждого компонента (или штата, если говорить о карте) создайте отдельную схему, более подробную (уже с указанием местных дорог и городков).
Аналогия с картой особенно хорошо подходит для архитектур, использующих микросервисы и API. Как и в штатах США, крупные города и автомагистрали остаются неизменными, но местные дороги в каждом штате и городе постоянно развиваются.
В продуманных схемах архитектуры отдельные части могут оставаться актуальными даже спустя годы развития проекта. Схема верхнего уровня должна показывать людям, не входящим в вашу команду, как все устроено, не загружая их излишними деталями или сложными терминами. Не удивляйтесь, если она появится в презентации для совета директоров, потому что хорошая схема — отличный способ продать свое видение.
11.2.8. Диаграммы процессов
Со схемой архитектуры тесно связаны диаграммы процессов. Они дают представление о том, как данные перемещаются по системе и что с ними происходит, когда они попадают в тот или иной сервис или библиотеку. Если схема архитектуры — это карта автомагистралей внутри штата или между ними, то диаграмма процесса — это наложенная на нее схема трафика из Google карт, показывающая, где находятся автомобили.
Диаграмма процесса — это логическая схема, показывающая, где данные хранятся, кэшируются и передаются из одного компонента в другой. Опять же, если она будет чрезмерно подробной — схема станет слишком сложной и в ней можно будет увязнуть.
Цель таких диаграмм — наглядно показать движение данных и на общем уровне обозначить пути и способы их перемещения, а также то, как данные попадают в систему и покидают ее.
11.2.9. Схемы сети
Схема сети похожа на схему архитектуры, но она создается с точки зрения структуры ваших сетей и серверов. Полезно указывать на ней сетевые адреса, маршруты, файерволы и шлюзы, которые соединяют части сети.
Если у вас есть физические серверы, на этой диаграмме нужно показать их местоположение (например, адрес ЦОД и координаты стоек в нем). Характеристики каждого элемента оборудования, в том числе даты покупки, гарантийный срок и настройки конфигурации, можно будет указать в отдельных документах.
11.2.10. Схемы баз данных
Базы данных лежат в основе большинства информационных систем, именно они хранят бесценные данные и связи между ними, без которых деятельность компании невозможна. Тем не менее, несмотря на всю важность этой области, документации по ней чаще всего недостаточно, хотя так быть не должно.
Существует, однако, множество инструментов (например, DB Schema), которые могут проанализировать реляционную базу данных и сгенерировать ее схему, при этом на основании внешних ключей (foreign keys) будут определены связи между таблицами. Вы можете дополнить эту схему комментариями, поясняющими бизнес-логику, которая стоит за структурой данных. Также все современные СУБД поддерживают возможность добавления комментариев к таблицам и столбцам наподобие того, как это делается в исходном коде.
Другие хранилища данных могут не поддерживать встроенные комментарии, и, следовательно, для них приходится вручную создавать дополнительные документы. Контроль этого нужно добавить в релизный цикл, чтобы, если что-то изменится, документация была обновлена.
Если ваша документация, описывающая структуру и месторасположение всех данных, составлена так, что будущие сотрудники смогут легко ее найти и использовать, то вы можете быть спокойны.
11.2.11. Соответствие нормативным требованиям
Вы можете работать в отрасли, где требуется наличие определенной документации, например описание процессов, результаты аудитов и периодические отчеты. Типичный пример таких отраслей — здравоохранение и финансы. Некоторые правительственные и военные проекты также требуют определенного уровня описания процессов (например, соответствия стандарту ISO).
Подробности, касающиеся соответствия HIPAA, PCI, ISO и т. д., выходят за рамки этой книги. Если вашей компании требуется сертификация — привлеките стороннего эксперта, который поможет организовать этот процесс. В больших аудиторских компаниях, например, этим занимаются целые департаменты. Эта задача на первый взгляд кажется пугающей, но, если подойти к ней правильно, сложностей не будет.
Какими бы ни были нормативные требования — считайте, что за ними стоит здравое желание добиться, чтобы все стороны действовали прозрачно. Организациям, в которых отсутствуют документация, процессы и регламенты, здесь будет тяжелее всего. Все придется создавать с нуля, и это может быть трудной и долгой задачей. Компаниям с четкой документацией и стандартами намного проще. Да, в них тоже наверняка есть области, требующие доработки, и части, которые не помешает усилить, но все уже движется в правильном направлении.
Соответствие требованиям — это, конечно, больше, чем просто документация, и все, что вы описали, необходимо выполнять на практике. Это может потребовать доработки кода или архитектуры, так что смотрите на это как на возможность для оптимизации и приведения в порядок различных частей проекта.
Большинство нормативных требований уделяют много внимания вопросам безопасности и работы с данными. Если вы считаете, что ваша организация может попасть в сферу действия таких требований, то начинайте изучать их заранее, готовиться и внедрять в команде соответствующие практики. Считайте, что это знак вашей исключительности. Именно вы отвечаете за защиту систем и данных вашей организации. Поэтому прислушивайтесь к любым полезным рекомендациям.
11.2.12. Учет лицензий и результатов аудитов
Вопрос, о котором обычно не думают, но рано или поздно он возникает, — как найти все ваши лицензии и купленное ПО. Заведите в базе знаний документ для учета всего используемого вами стороннего ПО, как купленного, так и с открытым исходным кодом. Сообщите команде, что важно вносить туда все, даже то, что кажется незначительным. Каждый раз, когда разработчик Java добавляет новую библиотеку в конфигурацию Maven или разработчик JavaScript подключает новый модуль npm, обновляйте этот документ, включая информацию об источнике ПО и условиях лицензии.
Проверка списка используемого ПО — это обязательная часть аудита due diligence, но на момент написания этой книги я еще не встречал команду, в которой эта информация была бы под рукой. Этот список необходим и в других случаях, например для продления и обновления лицензий, а также для того, чтобы понять, можно ли перенести ваше ПО в облачные сервисы, если вы захотите это сделать.
11.3. Документы для публикации (WHITEPAPERS)
Строго говоря, эти документы не относятся к внутренней документации компании, но упомянуть о них стоит. Компания может создавать и публиковать документы, предназначенные для внешней аудитории. В них описываются подходы или процессы компании в той или иной области.
Такие документы удобны, если клиентам требуется обучение для того, чтобы полноценно использовать ваш продукт. Они часто применяются в процессе продаж и прекрасно иллюстрируют профессионализм создателей продукта и глубину вложенных в разработку знаний.
В них не должно содержаться коммерческой тайны или подробного описания технологии. Цель здесь — познакомить читателя со стороны с вашим ходом мыслей, чтобы ему было легче взаимодействовать с продуктом. Вот что можно описать:
- Принципы безопасности API.
- Рекомендации по работе с данными.
- Рекомендуемые методы работы при интеграции API.
- Жизненный цикл данных.
11.4. Рекомендации
Создание документации, возможно, не самая эффектная часть вашей работы, но она является одной из важнейших, и без документации ваша команда не сможет успешно масштабироваться и расти. Вот некоторые лучшие практики и советы, которые помогут вам найти свой ритм:
- Тщательно выбирайте инструмент для вашей базы знаний, он должен предоставлять как можно больше функционала.
- Создайте шаблоны, чтобы можно было быстро добавлять новые страницы. Гораздо проще редактировать что-то, чем создавать с нуля.
- Начинайте с малого и двигайтесь не спеша. Это марафон, а не спринт.
- Поощряйте добавление в документацию информации из электронных писем и чатов.
- Быстро создать контент можно, записав видео или скринкаст.
- Описывайте, что делает исходный код, во время его ревью.
- Отрабатывайте и тренируйте все процессы управления вашим комплексом.
Итоги
- Записывайте знания сразу, пока они еще свежи.
- Выбор правильного инструмента облегчит всем внесение изменений и дополнений.
- Придерживайтесь простого стиля, чтобы те, кто не любит много писать, не боялись участвовать в создании документации.
- Видеоролики, голосовые заметки и схемы отлично подходят для описания деталей.
- Важно перепроверять все документы, касающиеся управления системой и ее поддержки.
- Даже краткие заметки или списки — это лучше, чем ничего.
Об автореАлан Уильямсон более 25 лет работает в области данных и технологий, внес свой вклад в спецификацию ключевых серверных Java API, создав использовавшийся в MySpace первый в мире движок CFML, написанный на Java. Он стал первым евангелистом Java (Java Champion) в Великобритании и опубликовал несколько книг по Java, посвященных Java Enterprise, сервлетам, JavaMail и работе с базами данных.
Он работал с частными инвестиционными компаниями более 15 лет, создавая и развивая команды, а также выполняя функции технического директора в ряде портфельных компаний. Алан являлся техническим директором и партнером MacLaurin Group и поддерживал деятельность портфельных компаний, консультируя технических директоров и системных архитекторов. Он осуществлял техническое руководство в нескольких организациях, поддерживаемых частными инвесторами. В настоящее время он является партнером группы портфельных операций в New Harbour Capital, чикагской инвестиционной компании, специализирующейся на предприятиях среднего бизнеса, и предоставляет услуги исполняющего обязанности технического директора и ментора.
Алан имеет степень в области computer science Университета Пейсли, Шотландия, со специализацией «цифровое управление».
О редакторе русского изданияЛогинов Олег Евгеньевич — разработчик, руководитель разработки и технический директор с более чем 20-летним опытом. Создавал успешные команды и проекты в крупнейших российских IT-компаниях и медиахолдингах: ВГТРК, «Газпром Медиа», VK, «Национальная Медиа Группа».
На практике знаком со всеми аспектами работы технического директора: от создания и эксплуатации технологий для высоконагруженных проектов с аудиторией в десятки миллионов пользователей до формирования команды, организации работы, планирования и бюджетирования.
Более подробно с книгой можно ознакомиться на сайте издательства:
Комментарии: 0
Пока нет комментариев