Как у вас построена система документирования при разработке продукта?

Как известно, мало создать хороший продукт: программу или устройство. Немаловажно не растерять при его создании накопленные знания. Чтобы сами производители могли повторить то же самое, а будущие владельцы сумели разобраться, как это работает и приспособить для своих нужд. Мы попросили наших экспертов поделиться опытом

«Единого решения для структуры хранения базы знаний не существует»

Михаил Андреянов, руководитель направления центра компетенций по банковским технологиям компании «Техносерв»

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

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

Безусловным лидером на рынке ПО для ведения баз знаний является Confluence. Продукт платный, но эффективный благодаря возможностям адаптации и наличию большого числа плагинов и расширений. Компании, которые ищут бюджетный вариант подобного сервиса, применяют MediaWiki или ведут свои базы в Google Docs/One Drive.

Хорошей альтернативой является решение от Microsoft – Team Foundation Server или его облачная версия Azure DevOps. Данный продукт доступен по подписке и при этом предлагает не только базу знаний, но и систему отслеживания задач, контроля версий (TFS и Git), Build-машину, а также магазин расширений с бесплатным контентом и многое другое.

Единого решения для структуры хранения базы знаний не существует. Каждая компания, команда или отдельный проект предъявляют свои требования к структуре, объему и форме документов.

Чтобы успешно сформировать базу, необходимо, во-первых, выделить ответственного сотрудника, который будет заниматься структуризацией.

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

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

«В компании Polarr Inc используется гибридная система документации на основе приложений Notion и Asana»

Даниил Вершинин, Polarr Inc, руководитель технического отдела dinqe@polarr.co

Документирование основных аспектов разработки, планирование архитектуры будущих приложений, а также анализ ошибок сохраняется в базе данных Notion.

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

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

Каждый отдельный продукт компании в Notion представлен деревом документов с четко определенным набором подразделов. Подразделы находятся в ведении определенных команд:

• Подраздел R&D содержит документацию об используемых в программном продукте проприетарных технологий и способах их применения;
• Подраздел дизайна содержит в себе все наработки в области визуальной составляющей продукта, включая шрифты, пиктограммы, цветовые решения;
• Маркетинговый подраздел содержит анализ рынка до запуска продукта, анализ аудитории;
• Инженерный подраздел содержит собственно специфичную документацию по архитектуре исходного кода программного продукта, а также все сопутствующие документы: схемы, диаграммы, отчеты, покрытие кода тестами и прочее;

Подраздел QA содержит отчеты об ошибках работы приложения, отзывах пользователей, статусе стабильности приложения.

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

Для документирования программных текущих задач и задач QA в Polarr используется Asana. Важно, что любые задачи для написания исходного кода обсуждаются в компании именно в Asana. Это делается именно для документирования действий инженерного отдела: чтобы каждый человек мог четко понимать, где закончилась предыдущая часть работы и с чего нужно начинать новый день. Такой подход помогает в работе Polarr, потому что состав компании – большое количество удаленных сотрудников, работающих во многих часовых поясах. Это означает, что документирование путем обмена сообщениями и новостями через Asana – самый верный способ «закрепить» информацию в удобоваримом для любого инженера виде.

Если Notion – это общее видение компании, а также «птичий полет» для всех происходящих в компании процессов, то Asana – это краткосрочное планирование двухнедельных спринтов, позволяющих постепенно приближаться к тем целям, которые были заложены в Notion.

Notion позволяет каждому в Polarr понять, над чем ведется работа, а также то, что каждая выполненная в Asana задача, обязательно поможет достичь общей цели.

«В процессах разработки и сопровождения мы пользуемся системами документирования разной сложности»

Михаил Адигеев, руководитель отдела программных разработок и поддержки компании «ГЭНДАЛЬФ»

Бывают такие случаи, когда достаточно документировать процесс в файлах Word или Excel – например, в таком виде фиксировать первичные требования клиента, ТЗ, инструкции. Самый простой способ хранения – в виде папки на файловом ресурсе или на корпоративном веб-портале, чтобы обеспечивать единое пространство для каждого проекта. Такой способ хранения подходит в случаях, когда необходимо эпизодически обращаться к конкретной информации, и этой информации немного.

Для контроля версий документов можно использовать папки, содержащие в названии дату или номер версии, а на веб-портале – указать в свойствах документа. Такая система удобна своей простотой, но подходит для простых, относительно коротких проектов.

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

Если вам необходимо хранить документы, связанные с конкретным проектом по разработке или сопровождению информационной системы, или относящиеся к взаимодействиям с клиентом (заказы на разработку, оплаты, акты, CRM), то оптимальный вариант – интеграция системы документирования с сопровождаемой системой или с системой учета/CRM. Это позволит увязать документацию с конкретными событиями и объектами системы.

«В проектах внедрения решений “1С” документирование происходит поэтапно по единому алгоритму»

Марина Дударева, менеджер по качеству отдела коммерческих проектов компании «ГЭНДАЛЬФ»

Первые документы, которые мы составляем и подписываем с клиентом – это договоры. Сначала заключается договор на предпроектное обследование, потом – на сам проект. К договору прилагаются устав, полноценное техническое задание и план-график проекта с определением целей, сроков, ключевых сотрудников с обеих сторон.

В процессе внедрения каждый этап выполнения работ документируется отдельно.

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

Затем клиент сам тестирует результат нашей работы в конкретной ситуации.

Это называется сценарным тестированием. По его итогам подписывается протокол, а далее следует этап обучения сотрудников клиента работе с новыми программами. Документируется это в протоколах проведения обучения и инструкциях.

Наконец, ввод в промышленную эксплуатацию фиксируется в журнале экспертного тестирования, который мы ведем совместно с клиентом.

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

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

Подводя итоги

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

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

Ответы присылайте на почту: aberezhnoy@samag.ru

Мы рады обсудить это на страницах нашего форума: http://samag.ru/forum/

На страницах социальных сетей:

Facebook: https://www.facebook.com/samag.ru

ВКонтакте: http://vk.com/samag

Twitter: https://twitter.com/samag_journal

1. https://www.notion.so
2. https://www.notion.so/Notion-Template-Gallery-181e961aeb5c4ee6915307c0dfd5156d  https://asana.com
3. https://medium.com/@benln/10-public-notion-templates-you-can-magically-copy-25d04c1e5da2

Ключевые слова: Confluence, notion, polarr, asana, производительность, документация

Комментарии могут оставлять только зарегистрированные пользователи