Неважно, работаете вы в небольшом стартапе или же в крупной корпорации, когда возникает необходимость в хорошей, ценной документации сервисов или проектов, то на ее месте зачастую обнаруживается огромный пробел.
Это может затрагивать многие процессы организации, начиная с дискуссионных форумов и выбора оптимального пути к цели до адаптации новых сотрудников, которым нужно разобраться в деталях работы и взаимодействия систем.
Но если эту проблему все столь явно ощущают на собственной шкуре, то почему она до сих пор актуальна?
Почему документация так важна?
Совещания
Если вам приходилось участвовать в обсуждении нового проекта, для которого компании нужно определить удачное место в имеющейся базе кода, то вы знаете, какое количество идей, предложений и решений на таких встречах анализируется. Их число возрастает в геометрической прогрессии согласно количеству присутствующих на совещании людей.
Каждое предложение несет свои собственные достоинства и недостатки, которые нужно обсуждать.
А теперь представьте, что закончили совещание и вернулись к повседневной работе (написанию кода и тому подобному). Верите ли вы, что сможете сохранить в памяти и через несколько недель вспомнить обсуждавшиеся на встрече предложения? А их плюсы и минусы? Какое было отклонено и почему? Какие вместо каких выдвигались?
Вряд ли. И признание этой “слабости” не выставляет вас в плохом свете — даже наоборот. Знание собственных слабостей как раз-таки делает вас сильнее, ведь это единственный способ с ними бороться и минимизировать их влияние.
Что же нужно делать, чтобы избежать бесследной траты этого часа вашей жизни, времени ваших коллег и денег компании? Лучше всего такие встречи документировать.
Создание на совещаниях заметок, которые при необходимости будут доступны в том числе для ваших коллег, окажется прекрасным способом в нужный момент вспомнить, о чем тогда шла речь. Заметки можно делать как в процессе совещаний, так и после них. Только не затягивайте слишком долго между самой встречей и ее фиксированием. В противном случае половину, а то и более, вы просто не вспомните.
Обязательно запишите основные точки обсуждений, предложения, их плюсы и минусы, принятые решения и намеченные действия.
Путешествие во времени
Очень философский заголовок, но при этом верный.
Если все идет как положено, и ваш бизнес растет в своих потребностях, то решение, принятое год назад, вполне может негативно отразиться на этих самых новых потребностях.
В таком случае вам нужно будет объяснить старшему руководству, почему все произошло именно так. А самое интересное знаете в чем? Вы просто не вспомните сути.
Если же у вас будет запись встречи, на которой было принято то самое роковое решение, то вы и ваши менеджеры вспомните, что принимали его ввиду строгого, ограниченного временем дедлайна, который компании требовалось соблюсти, или по любой другой причине.
Обсуждение идей
Работая в офисе, инженеры, как правило, обсуждают идеи возле доски. На ней мы отображаем свои замыслы и объясняем свои предложения. Нередко для этого используются UML-диаграммы.
Если у вас будет шанс, то обязательно сделайте несколько фото доски перед уходом. В противном случае следующая команда беспощадно сотрет все труды ваших длительных обсуждений с коллегами.
Но что, если вы работаете удаленно?
Когда я впервые столкнулся с этой проблемой, люди просто пробовали объяснять свои мысли на словах. Сложность в том, что естественный язык подвержен особенностям восприятия, и понимаемый смысл сказанного предложения может не всегда совпадать с идеей его автора.
Что я посоветую? Используйте любой инструмент для рисования или UML (унифицированного языка моделирования) и откройте демонстрацию экрана. Пусть люди видят, как именно вы понимаете сказанное. Это позволит всем оставаться в согласованном потоке мысли.
Поначалу такой вариант может казаться медленным, так как на зарисовку идей собеседников потребуется какое-то время, но так ваше взаимодействие станет намного эффективнее, поскольку из него исчезнет по меньшей мере часть разрыва в восприятии.
Адаптация
Подключение к процессу нового члена команды всегда сопряжено с трудностями. Необходимо возвращаться к основам и объяснять, что делает ваша система, и как каждый ее элемент вписывается в общую архитектуру.
Если делать это всякий раз, когда в вашу компанию приходит новый человек, то времени, а значит и денег компании, на подобное ознакомление будет уходить очень много.
Если же у вас будет документация, разъясняющая основы работы вашей системы, она позволит предоставить новичку автономность.
Будьте креативны! Если все сделать по уму, то создание плана ознакомления может освободить уйму вашего времени под другие задачи. При этом сам план, как правило, не потребует особых корректировок.
Постройте диаграммы и схемы, которые наглядно покажут, как все работает. Снимите видео. Воспользуйтесь этой возможностью, чтобы повысить и свои знания.
Проектирование не только для архитекторов ПО
Если большую часть своей карьеры вы проработали в крупной организации, проектирование систем и схем их взаимодействия наверняка не являлось существенной частью ваших обязанностей. В компании, скорее всего, были архитекторы, которые этим занимались. Вы писали код, а они проектировали линии и стрелочки, указывая на то, как вам нужно создавать сервисы.
При этом возникает соблазн расслабиться и просто следовать их документации. Проблема же в том, что документация команды архитекторов будет представлять более обобщенное видение системы. В ней не будет отмечена конкретная логика вашего сегмента или сервиса. Именно вы и ваша команда являетесь теми, кто в подробностях знает его работу на локальном уровне.
Расширьте существующую документацию дополнительными деталями. Эти детали иногда составляют разницу между принятием плохого или хорошего решения, о чем может стать известно только спустя месяцы.
К тому же, таким образом вы будете тренировать навыки проектирования архитектур и систем, что никогда не станет лишним для инженеров ПО.
У большинства инструментов проектирования много недостатков
Поговорим немного об инструментах проектирования.
Большая их часть основана преимущественно на визуализации. Это значит, что для выражения своих мыслей вам нужно рисовать линии и блоки.
Слишком много внимания в таких инструментах уделяется тому, как все выглядит, а не легкости создания диаграммы, ее изменения и последующей доработки.
Если вы строите диаграмму классов, к примеру, на Draw.io, то вам нужно искать подходящие элементы, перетаскивать их, соединять их и сопровождать описанием. Нужно будет следить за тем, чтобы линии выглядели правильно и не допускали неточной интерпретации. Нужно в целом следить, чтобы вся диаграмма смотрелась “хорошо”.
Теперь предположим, что вам нужно изменить эту диаграмму, добавив несколько компонентов. Для этого потребуется все реорганизовать, чтобы они в нее вписались, и при этом снова убедиться, что она выглядит правильно. Умножьте эти усилия на количество раз, которое вам нужно ее обновлять.
Подобные инструменты созданы не для разработчиков. Они могут быть полезны для продакт-менеджеров, дизайнеров и старшего руководства, но не для разработчиков, так как не учитывают естественную леность, которая заставляет нас повышать эффективность разработки.
И все же я могу назвать по меньшей мере один инструмент, который разработан по иному принципу.
PlantUML
Познакомился с PlantUML я в колледже. Перед нами стояла задача построить диаграммы, и профессор потребовал использовать именно этот инструмент. На тот момент мы еще ничего подобного не знали. Основным средством, которое мы применяли, был Visual Paradigm, тоже являющийся визуальным.
Поначалу я был не в восторге от PlantUML. Почему? Все просто: я не знал синтаксис и не понимал, как его использовать. Теперь же я очень признателен тем профессорам, которые познакомили меня с этим прекрасным инструментом.
Но что его так отличает от других?
Все!
Начнем с того, что в нем вы ничего не рисуете. Вы пишете код. Код, который компилируется и на выходе дает изображение. Это ускоряет процесс проектирования, позволяет копировать примеры из других диаграмм и адаптировать их к новой, сохраняя контроль версий.
На этом изображении вы наблюдаете образец диаграммы, которую я создал для своей магистерской диссертации. На ней отображена последовательность вычисления стоимости сервиса. Как видите, у меня нет инструкций по настройке изображения диаграммы. Я лишь устанавливаю взаимодействия между каждым компонентом, а все остальное делает PlantUML.
Этот код я разместил в репозитории Git, где могу контролировать изменения, принимать запросы на слияние для обновлений и управлять диаграммой как любым другим фрагментом кода.
Будущее инструментов для инженерии ПО
Если мы хотим, чтобы разработчики документировали то, что они делают, то нам нужно больше инструментов, подобных PlantUML. Нам нравится писать код. А трата времени на возню с маленькими блоками и цветными кнопочками точно не то, что нужно.
Тем не менее даже в PlantUML есть возможность улучшений. Одна из самых раздражающих его особенностей в отсутствии возможности использовать несколько страниц, обращающихся к одному коду для компиляции UML. Мне приходилось повторять код на разных страницах, и при каждом внесении изменений все эти страницы нужно было обновлять. Если сделать так, чтобы страница обращалась к репозиторию Git, скачивала код, компилировала его и затем генерировала изображение, то это еще больше повысит удобство обслуживания таких диаграмм.
К тому же, изображения, сгенерированные PlantUML, выглядят абсолютно старомодно. Я, конечно, говорил, что разработчиков не волнует визуальная часть, но все же… Мы с вами находимся в эпохе материального дизайна, а не HTML 1.0.
Если исправить эти два недостатка, то создание документации станет сплошным удовольствием. Этот процесс превратится из монотонной задачи перетаскивания элементов в увлекательное написание кода диаграмм.
Важность внутренних установок
Как и в большинстве случаев, понимание ценности хорошей, актуальной документации непосредственно связано с умственным настроем. Если мы привыкли обходиться без этого, то перестроиться будет нелегко.
Начните с создания документации для наиболее полезных вещей. Делитесь ей с другими. Постепенно призывайте коллег делать то же самое. Естественно, невозможно добиться, чтобы каждый создавал собственную документацию, но начинать с чего-то нужно.
Выработайте установку, согласно которой вы будете воспринимать проектирование и документацию как часть процесса разработки. Станьте послом этой модели мышления и распространите ее среди своих коллег.
Спасибо за внимание!
Читайте также:
- Чем лучше образование, тем умнее ИИ
- 8 главных качеств технического менеджера
- 9 привычек неумелого разработчика
Читайте нас в Telegram, VK и Яндекс.Дзен
Перевод статьи Emanuel Marques: This Is Why Most Software Engineers Don’t Write Documentation
